SolTrace Qt GUI

This directory contains the Qt-based SolTrace graphical application. It is a new, alpha-stage interface for building SolTrace models, running simulations, and inspecting results.

The application is under active development. Expect incomplete workflows, rough edges, and behavior that may change quickly. The built-in documentation panel is the best place to start once the application is running.

Requirements

• Qt 6.11 or newer, including these additional components:
  • Qt Core
  • Qt Gui
  • Qt Quick
  • Qt Quick 3D
  • Qt Quick Timeline
  • Qt Widgets
  • Qt Graphs
• CMake 3.16 or newer
• A C++20-capable compiler
• Network access during the first CMake configure, unless the CPM dependencies are already cached

The GUI builds against libraries from the repository's coretrace directory, so build it from that repository level rather than copying gui/ elsewhere.

To obtain Qt, you can:

• Download and install prebuilt packages using Qt's official installer (requires free Qt account). Though this is an open source framework, the Qt organization gates binary downloads behind an account for hosting cost reasons
• Use your platform's built in package manager, if available
  • Mac users can use brew to obtain the latest Qt
  • Linux users may not have the latest 6.11 version in their distribution repositories
• Use a tool like https://github.com/miurahr/aqtinstall to install binary packages
  • Example: aqt install-qt mac desktop 6.11.1 clang_64 -m qtgraphs qtquick3d qtquicktimeline
• Compile from source from https://github.com/qt (not recommended due to build complexity)

Recommended Developer Workflow: Qt Creator

Qt Creator is the recommended way to work on this GUI during development.

1. Open Qt Creator.
2. Choose File > Open File or Project....
3. Select <path_to_soltrace>/CMakeLists.txt.
4. Choose a Qt 6.11+ kit with a C++20-capable compiler. Note: For building OptiX on Windows, use MSVC 2022 64-bit compiler.
5. Enable the SOLTRACE_BUILD_GUI option.
6. Configure the project.
7. Build and run the SolTrace target.

If CMake cannot find Qt, check that the selected kit points at the intended Qt installation. If CMake cannot fetch dependencies, make sure the machine has network access or that the CPM cache already contains the required packages.

Command Line Build

From the repository root:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DSOLTRACE_BUILD_GUI=On
cmake --build build --target SolTrace

Run the built application from the generated build tree. The exact path depends on platform and generator. Common examples:

# macOS bundle
open build/gui/SolTrace.app

# Linux or single-config generators
./build/gui/SolTrace

# Windows multi-config generators
build\gui\Release\SolTrace.exe

Install/Deploy

The CMake project includes install and Qt deployment rules. These are still under development.

For a local install:

cmake --install build --prefix install

On multi-config generators:

cmake --install build --config Release --prefix install

Deployment is still part of the alpha workflow, so prefer running from Qt Creator or from the build tree while developing.

Release packaging isolation

Release packaging intentionally remains separate from the general CMake install rules. Local developers may use their own Qt, Embree, TBB, and CUDA installations, while official artifacts use pinned dependencies and collect the corresponding license files in CI. Making those release-only paths part of the normal install rules would couple local installs to the release environment.

The release workflow therefore installs into a staging directory, then uses the Python tools under scripts/release to add runtime libraries, licenses, and validation. The standard and OptiX Windows MSIs are generated by a standalone CPack/WiX configuration from a filtered installer-root; CPack does not rerun the project's install rules. They use separate product identities and install directories so they can coexist. The portable ZIP continues to use the complete staged install tree. See scripts/release/README.md for maintainer commands and the detailed artifact flow.

The macOS artifact is ad-hoc signed after staging so all bundled executables have internally consistent signatures. Ad-hoc signing is not a substitute for a Developer ID certificate or notarization, and downloaded builds can still require the user's explicit approval under Gatekeeper. Trusted, prompt-free distribution will require adding Developer ID signing and notarization to the release workflow.

Translations

The Qt Quick GUI uses Qt Linguist for user-interface translations. User-facing QML strings should be wrapped with qsTr("..."); C++ strings that become visible in the UI should use the appropriate Qt translation API for that class. Do not translate internal identifiers such as model role names, enum names, serialized values, filenames, resource paths, icon glyphs, or units that should remain standardized.

Translation source files live in gui/translations/. The current Spanish catalog is gui/translations/soltrace_es.ts. Released translation catalogs are compiled to .qm files by CMake and embedded into the application resource prefix :/i18n. At runtime, the GUI loads the selected locale's catalog and asks the QML engine to retranslate visible bindings.

The line numbers stored in .ts files are location metadata. Moving a translated string within the same QML component may update the <location> entry when update_translations runs, but it should not invalidate the translation. Qt matches messages primarily by context, source text, and optional disambiguation/comment. A translation is more likely to become unfinished when the source text changes, the string moves to a different QML context, or placeholders such as %1 or %n are added, removed, or changed.

Updating existing translations

After adding or changing translatable UI strings, update the .ts catalog from the build directory:

cmake --build . --target update_translations

Then edit the relevant gui/translations/*.ts file with Qt Linguist or a text editor. Preserve placeholders such as %1, %n, and markup such as <em>...</em> or <sub>...</sub> exactly unless the source string itself is being changed. Remove type="unfinished" only when the translation has been reviewed.

Compile the runtime catalogs and rebuild the app:

cmake --build . --target release_translations
cmake --build . --target SolTrace

release_translations should report zero unfinished translations for catalogs that are expected to ship complete.

Adding new translatable strings

Use complete user-facing phrases instead of assembling translated fragments. For example, prefer qsTr("Delete Geometry") over qsTr("Delete") + " " + qsTr("Geometry"). Word order, grammar, and gender can change between languages, so translators need the whole phrase.

Use placeholders for dynamic values:

text: qsTr("Delete %1").arg(itemName)

Preserve placeholders such as %1, %2, and %n in every translation. If the same English source text has different meanings in different places, provide a disambiguation/comment with Qt's translation APIs so translators can tell which meaning is intended.

Place qsTr() at the UI binding or user-facing API boundary. Avoid translating internal data used by logic, persistence, or model lookup, such as enum names, role names, IDs, file paths, resource paths, and serialized values. Rich text is allowed when the label needs it, but translators must preserve tags such as <em> and <sub>.

Adding a new language

To add a language, add a new .ts file under gui/translations/ and list it in SOLTRACE_TRANSLATION_FILES in gui/CMakeLists.txt. Use a locale suffix in the filename, for example soltrace_fr.ts or soltrace_pt_BR.ts.

Run update_translations, fill the new catalog, then run release_translations. The generated .qm file is embedded automatically through the existing CMake translation resource setup. Finally, expose the new locale in the GUI language selector so users can choose it.

Inline Documentation

Editable inline documentation lives in gui/docs_source. The generated runtime resources live in gui/docs and are the only documentation files packed into the application.

Inline documentation files are addressed by dotted keys that follow the source path. For example:

gui/docs_source/en/configure/layout/coordinates.md
  -> configure.layout.coordinates

Use the same path under each locale directory. Documentation can include normal Markdown text and display equations delimited with $$ ... $$. Equations are rendered to SVG by Typst during processing.

To regenerate the packed docs after editing sources:

cd gui
python3 scripts/process_docs.py

The processor removes the previous gui/docs tree before writing new output, so stale generated documents do not remain in the application resources. Typst is only required when updating documentation, not for ordinary app builds.

Notes

• The executable target is named SolTrace.
• The QML module URI is SolTrace.
• Edit application documentation in gui/docs_source, then run gui/scripts/process_docs.py to regenerate gui/docs. Only the generated gui/docs tree is embedded as Qt resources.
• Assets under gui/assets are embedded as Qt resources.
• Third-party header-only dependencies such as EnTT and magic_enum are fetched through CPM during configuration.