Installation Guide

Installation Guide & Execution

DSEpy is currently in active development and testing. At this stage, it runs directly from the Python source code within CloudCompare's Python environment.

This guide covers system prerequisites, step-by-step setup, script execution inside CloudCompare, and internationalization settings.

---

1. Prerequisites & Dependencies

Before running DSEpy, ensure your workstation meets the following requirements:

• Host Application: CloudCompare (v2.12 or newer recommended) with Python support enabled.
• Python Environment: Python 3.9+ (configured within or linked to your CloudCompare installation).

Core Dependencies

DSEpy relies on the following standard Python libraries:

• numpy & scipy: Vector mathematics, spatial indexing, and matrix operations.
• matplotlib: Stereonet projection rendering, density contours, and color mapping.
• Pillow (PIL): Image handling and icon processing for the UI.

---

2. Setup & Execution Steps

Step 1: Download or Clone the Repository

Clone the repository using Git or download the source code as a .zip archive:

git clone [https://github.com/adririquelme/DSEpy.git](https://github.com/adririquelme/DSEpy.git)

Step 2: Install Python Dependencies

Install the required packages into the Python environment used by your CloudCompare installation:

# Run using the Python executable associated with CloudCompare
python -m pip install -r requirements.txt

Step 3: Run DSEpy in CloudCompare

1. Open CloudCompare and load your 3D point cloud (ensure normal vectors are calculated).
2. Open the Python Script Editor / Console inside CloudCompare.
3. Open or execute main_gui.py from the downloaded DSEpy folder:

exec(open("path/to/DSEpy/main_gui.py").read())

ℹ️ Roadmap Note: Standalone executables (.exe) and potential native C++ CloudCompare plugin integration are planned for future releases as community testing progresses.

---

3. Internationalization (i18n) & Language Support

DSEpy features dynamic multi-language support managed through lightweight JSON translation dictionary files stored in the locales/ directory. The base translation file is en.json (English), which serves as the reference template for all interface strings, menu items, tooltips, and dialog messages.

How i18n Works in DSEpy

At application launch, DSEpy scans the locales/ folder for available .json language files. When a user selects a language in the interface preferences:

1. The corresponding translation dictionary is loaded into memory.
2. The UI framework maps text identifiers (keys) to their localized strings (values).
3. If a specific text key is missing from a translated file, DSEpy automatically falls back to the default English string defined in en.json.

Structure of Translation Files

Translation files use standard nested JSON objects representing GUI modules and components.

Important Rule: When translating, only edit the values on the right side of the colon (:). Do not modify the keys on the left side, as they are hardcoded into the application logic.

{
  "main_window": {
    "title": "DSEpy - Discontinuity Set Extractor",
    "file_menu": "File",
    "tools_menu": "Tools"
  },
  "spatial_clustering": {
    "tab_title": "3. Spatial clustering and plane fitting",
    "k_neighbor_label": "K-th Neighbor (K):",
    "coplanarity_merge_tooltip": "Tolerance multiplier (k_sigmas) to merge coplanar patches into a single plane."
  }
}

Step-by-Step: Adding a New Language

Users and contributors can easily add support for a new language without compiling code or modifying the core repository structure:

1. Locate the Base File: Navigate to the locales/ folder in the root directory of DSEpy and locate en.json.
2. Duplicate & Rename: Copy en.json and rename the new file using the corresponding ISO 639-1 language code (e.g., es.json for Spanish, fr.json for French, de.json for German, ca.json for Catalan).
3. Translate Values: Open the new .json file in a text editor (e.g., VS Code, Notepad++) and translate all string values into the target language.
4. Save and Restart: Save the file inside the locales/ directory and restart DSEpy—the new language will automatically appear in the interface language dropdown menu.

Translation Guidelines & Best Practices

• Format Placeholders: Preserve dynamic variable placeholders (e.g., {0}, {count}, %s) as they appear in the original text.
• Special Characters & Escaping: If a double quote (") appears within a string value, escape it with a backslash (\").
• UTF-8 Encoding: Always save translation JSON files with UTF-8 encoding to ensure correct rendering of special characters, accents, and non-Latin scripts.

---

🔗 Next Steps

• Get an overview of the full analysis process in Workflow Overview.
• Learn how to calculate point normals and set poles in Stereonet & Poles.
• Explore orientation grouping in Set Classification.