qgis-tem-loader

qgis plugin for loading TEM geophysical inversion XYZ files as 3D objects
git clone git://src.adamsgaard.dk/qgis-tem-loader # fast
git clone https://src.adamsgaard.dk/qgis-tem-loader.git # slow
Log | Files | Refs | README | LICENSE Back to index

AGENTS.md (2785B)

      1 # TEM Loader Plugin
      2 
      3 QGIS 3.40+ plugin for loading Time-Domain Electromagnetic (TEM) inversion XYZ files as styled 3D vector layers. Python, no external dependencies beyond QGIS itself.
      4 
      5 ## Commands
      6 
      7 ```sh
      8 make test      # run the unittest suite
      9 python3 -m unittest discover -s test -p 'test_*.py'  # same test runner without Make
     10 python3 -m unittest test.test_core.ProcessXYZTests.test_temimage_4_0_4_6_fixture  # single test
     11 make package   # build tem_loader.zip for installation
     12 make clean     # remove the zip
     13 ```
     14 
     15 CI runs `make test` on Python 3.12; the GitLab pipeline also produces `tem_loader.zip` as an artifact.
     16 
     17 ## Boundaries
     18 
     19 **Allowed without asking:**
     20 - Read any file, list directories, run single-file type checks and tests
     21 - Create or edit files in `tem_loader/`, `test/`, and `tem_loader/styles/`
     22 
     23 **Ask first:**
     24 - Installing new Python dependencies (project has none)
     25 - Deleting test fixtures from `test/data/`
     26 - Pushing to git (`git-push.sh` pushes to origin, own, and geus remotes)
     27 
     28 **Never touch:**
     29 - `.env`, secrets, or credentials
     30 - Binary video files (`*.mov`, `*.mp4`) — they are demos, not code
     31 - Large XYZ fixture data in the project root (development samples only)
     32 
     33 ## Architecture
     34 
     35 - `tem_loader/core.py` — XYZ parsing, CSV writing, resistivity color mapping. No QGIS dependency; fully unit-testable.
     36 - `tem_loader/tem_loader.py` — QGIS plugin glue: dialog, layer creation, CRS resolution, styling, group organization.
     37 - `tem_loader/styles/*.qml` — QGIS layer style files for points, DOI, and layers (supports 3D renderer with dynamic color).
     38 - `test/data/` — fixture XYZ files for the three supported export families: TEMImage, Aarhus Workbench, and SCI Workbench.
     39 
     40 ## Conventions
     41 
     42 - Fallible operations raise `ValueError` with descriptive messages; callers catch and present them to the user (not swallowed).
     43 - Multiple file processing continues after errors per-file, collecting failures into a single warning dialog.
     44 - CRS resolution: source EPSG from file metadata > project CRS > EPSG:4326 fallback.
     45 - Test fixtures live in `test/data/`; tests assert counts, specific field values, and QXML structure (for style verification).
     46 
     47 ## Git
     48 
     49 - Commit messages follow conventional commits, for example `feat(parser): ...`, `fix(qgis): ...`, `build: ...`, and `chore(release): ...`.
     50 - Do not push without approval; `git-push.sh` pushes to `origin`, `own`, and `geus`.
     51 
     52 ## Gotchas
     53 
     54 - `core.py` must remain free of QGIS imports — it is the only module tested without a running QGIS instance.
     55 - The SCI Workbench format aggregates per-layer rows into soundings at parse time; its code path diverges from the other two formats.
     56 - XYZ files with an extra leading index column (pandas-style) must be handled by dropping the first value before zipping.