# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Behavioral Guidelines (Binding)

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

### 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them — don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

### 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

### 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it — don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

**Exception — Tech debt must be fixed, not deferred:** When you discover a real bug,
broken behavior, or technical debt while working (even if it predates this change and
you didn't introduce it), fix it — do not use "not introduced by this round / pre-existing"
as a reason to leave it. Surface it, then handle it. (User directive, 2026-06-25, binding.)
This overrides the "don't fix what isn't broken" bias above *for genuine defects* — it does
not license cosmetic refactors or unrequested rewrites.

**Do it yourself — never offload work you can do (User directive, 2026-06-25, binding):**
If you have the tools to do something, DO IT — never tell the user to do it for you.
Read the logs yourself (`%LOCALAPPDATA%/Geomative/Geopro3/logs/geopro_*.log` via Bash/grep),
inspect data/fixtures yourself, build and link yourself (`build.bat app` via PowerShell),
diagnose by adding logging and then reading that log yourself. The ONLY things to ask the
user for are: (a) closing a running app so the exe can relink (LNK1104 — a lock only they can
release), and (b) genuine product decisions. Do not ask the user to read logs, inspect data,
run diagnostics, or interpret output — that is your job.

### 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" -> "Write tests for invalid inputs, then make them pass"
- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
- "Refactor X" -> "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] -> verify: [check]
2. [Step] -> verify: [check]
3. [Step] -> verify: [check]
```

---

## Project Overview

Geopro 3.0 desktop client: a geophysical exploration data visualization application
(Qt 6 + VTK 9, C++17, Windows/MSVC). Replicates the core "Project Analysis View" from
Geopro 3.0 web.

Tech stack: Qt 6.11 (QtWidgets) + VTK 9.6 + CMake/Ninja + MSVC 2022/2026 + vcpkg
(non-Qt deps only) + ADS (docking) + GDAL/PROJ + OpenSSL + QtKeychain + Qwt.

---

## Build System

**Prerequisites:** Visual Studio 2022/2026 (Desktop C++ workload), Git, vcpkg with
`VCPKG_ROOT` env var set. Qt 6.11.1 MSVC kit at `D:/Qt/6.11.1/msvc2022_64`. VTK 9.6.2
prebuilt at `external/vtk-install`. All Qt-dependent libs (VTK/ADS/QtKeychain) link
against the official MSVC Qt kit; only non-Qt deps (GDAL/PROJ/OpenSSL/Eigen/gtest/etc.)
come from vcpkg.

**Rule:** `cmake` / `ninja` / `cl` are NOT on PATH by default. Build only inside an
activated MSVC environment. `build.bat` handles this automatically via vswhere.

### Primary: `build.bat` (recommended)

Run from repo root in **cmd** (not PowerShell for parameter passing):

| Command | Action |
|---|---|
| `build` or `build app` | Incremental build of `geopro_desktop` (default) |
| `build run` | Build and launch `geopro_desktop.exe` |
| `build test` | Build and run unit tests via ctest |
| `build all` | Build all targets |
| `build configure` | Force re-configure CMake (after CMakeLists changes or new sources) |
| `build rebuild` | Clean rebuild (`--clean-first`) then launch |

### Alternative: Manual CMake

Open "x64 Native Tools Command Prompt for VS", then:

```bat
set CMAKE="%VSINSTALLDIR%Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe"
%CMAKE% --preset msvc-release
%CMAKE% --build build/release --target geopro_desktop
%CMAKE% --build build/release --target geopro_tests
ctest --test-dir build/release --output-on-failure
```

(Debug: replace `msvc-release` with `msvc-debug` and `build/release` with `build/debug`.)

### Build Targets

- `geopro_desktop` — Main executable at `build/release/src/app/geopro_desktop.exe`
- `geopro_tests` — Unit test executable, discovered by ctest
- `render_verify` — Offline PNG render verification (`tests/spike/`)
- `grid_contour_spike` / `slice_alpha_probe` — Spike verification tools

**Incremental builds:** Changing `.cpp/.hpp` only needs `--build`. Changing
`CMakeLists.txt` or adding new source files needs `build configure` or `--preset`.

**LNK1104:** If linking fails with "file in use", close any running `geopro_desktop.exe`
first (the only thing to ask the user for).

---

## Testing

Framework: **Google Test** for core/data/render; **Qt Test** (QSignalSpy) for
controller/net. Discovered via `gtest_discover_tests` with `DISCOVERY_MODE PRE_TEST`
(because Qt DLLs are copied POST_BUILD; discovering at build time would fail with
0xc0000135).

### Running Tests

```bat
build test                          # All tests via build.bat
ctest --test-dir build/release --output-on-failure -R <pattern>   # Filter by regex
```

Running a **single test case** (example):
```bat
# After building geopro_tests:
build\release\tests\geopro_tests.exe --gtest_filter="*ColorScale*"
```

Some render/data tests require `PROJ_DATA` (set automatically by ctest from the vcpkg
install tree). If running the test exe directly, ensure `external/vtk-install/bin` and
vcpkg DLLs are on PATH.

### Render Verification

Rendering correctness **must be verified with offline PNG pixel checks**, not just
"doesn't crash". Use `tests/spike/render_verify.cpp`:

```bat
build all   # builds render_verify
# Ensure PATH includes external/vtk-install/bin and vcpkg_installed/x64-windows/bin
# Ensure PROJ_DATA and GDAL_DATA are set if testing terrain/voxel
build\release\tests\spike\render_verify.exe
# Inspect output PNGs at D:/dev/spike_data/verify_*.png
```

---

## Code Style

- `.clang-format`: BasedOnStyle Google, C++17, 100 column limit, 4-space indent, braces after class/function.
- `.clangd`: Compilation database at `build/debug`. Strict unused-include checks.
- File encoding: **UTF-8 without BOM**. Do NOT use PowerShell `Set-Content -Encoding UTF8`
on source files (it corrupts Chinese comments).

---

## Architecture

Six-layer directory structure under `src/`:

```
src/core/        Pure business logic. ZERO Qt/VTK includes. Independently unit-testable.
                 model/ (Project, ColorScale, Grid, ScalarVolume, Anomaly...)
                 geo/   (LocalFrame, GeoLocalFrame, CrsTransform)
                 algo/  (IInterpolator, IdwInterpolator, VolumeBuilder)
src/io/          I/O parsers. Pure C++17 where possible.
                 gpr/   (IprbReader, IprHeader, GprSurveyAssembler, GpsTrack)
src/data/        Data access layer. Async repository contracts (QFuture/cancel/paging).
                 repo/  (IAsyncProjectRepository, IDatasetRepository, LocalSampleRepository)
                 api/   (ApiDatasetRepository, ApiProjectRepository, NavRequest)
                 dto/   (JSON DTOs + mapping to domain models)
                 store/ (ChunkedVolumeStore, pyramid LOD, streaming writes)
src/net/         Network & auth. ApiClient, AuthService, RsaEncryptor, Credential (QtKeychain).
src/render/      VTK rendering layer. Owns ALL actors and the single vtkRenderWindow.
                 Scene.hpp is the single owner of the render window.
                 actors/     (ScatterActor, GridContourActor, CurtainActor, VoxelActor, AnomalyActor, TerrainActor, ElectrodeActor)
                 interact/   (InteractionManager, SliceTool, PickInteractorStyle, AnomalyDrawTool)
                 source/     (Volume render sources: WholeVolumeSource, OutOfCoreSource, ViewAdaptiveVolumeSource)
                 ground/     (TileMath for basemap tiles)
src/controller/  Orchestration. Signals/slots wired in wireUp() methods.
                 (WorkbenchNavController, DatasetDetailController, VtkSceneController)
src/app/         Entry point + MainWindow + all QtWidgets panels and dialogs.
                 panels/     (ObjectTreePanel, DatasetListPanel, DatasetDetailPanel, AnomalyListPanel, etc.)
                 panels/chart/   (Qwt-based detail charts: GridDataChartView, ScatterPlotItem, ContourPlotItem)
                 panels/columns/ (Category analysis tabs)
                 panels/web/     (ProjectWebView with QWebEngineView)
```

**Architecture rules (binding):**
- `core` must NEVER `#include` any Qt or VTK header.
- VTK actors / `vtkRenderWindow` are created and owned ONLY by `render`. `view`/`app`
  holds the `QVTKOpenGLStereoWidget` shell but must NOT create actors directly.
- Signal/slot connections are concentrated in `*Controller::wireUp()` or `MainWindow`.
- All file paths use `QStandardPaths` (Qt) or project-relative logic; no hardcoded paths.

### Coordinate System

- Data source CRS: **EPSG:4547** (CGCS2000 / 3-degree Gauss-Kruger CM 114E) for
  `projectX/projectY` in local survey data.
- Project world coordinate: `core::GeoLocalFrame` (lat/lon -> local meters, equidistant
  cylindrical), shared across all views for registration.
- DEM/imagery: EPSG:3857 (Web Mercator), reprojected via PROJ/GDAL at runtime.
- Rendering convention: depth `y` increases downward -> VTK `z` is negated.

---

## Key Dependencies & FetchContent

- **Qt 6.11.1**: Official MSVC kit at `D:/Qt/6.11.1/msvc2022_64`. `CMAKE_PREFIX_PATH`
  points here. Only one Qt exists in the build.
- **VTK 9.6.2**: Built from source against the same Qt, installed to `external/vtk-install`.
  Required components include `GUISupportQt`, `RenderingOpenGL2`, `InteractionStyle`,
  `FiltersSources`, `RenderingVolumeOpenGL2`, `InteractionWidgets`, `FiltersGeometry`,
  `IOImage`.
- **ADS (Qt-Advanced-Docking-System) 4.3.1**: FetchContent from GitHub. Linked as
  `ads::qt6advanceddocking`.
- **QtKeychain 0.14.0**: FetchContent, static-linked. `BUILD_WITH_QT6=ON`.
- **Qwt 6.2**: Source expected at `external/qwt-src`. Included via `cmake/qwt.cmake`.
- **vcpkg deps**: eigen3, gdal, gtest, nlohmann-json, openssl, proj.

---

## Important Project Conventions

- **ColorScale / colorBar values**: Use real non-uniform segment values from the dataset.
  Uniform grading produces incorrect all-blue renders.
- **2D map vs 3D view**: These are **different content**, not the same scene with a
  different camera. 2D map = `MapLineActor` (survey line trajectories, top-down). 3D view
  = `CurtainActor` (vertical cross-section walls) + voxel + slice + terrain.
- **Data detail** (bottom panel) = single-dataset analysis view (`GridContourActor` for
  #18 grid, `ScatterActor` for #17 raw data).
- **Rendering changes must be verified** with `render_verify` offline PNG before app
  integration, then manually in-app.
- **Build and link yourself** — do not ask the user to run builds, read logs, or inspect
  data. The only exception is closing a running `geopro_desktop.exe` for LNK1104.

---

## Memory

- See `.claude/projects/E--gitea-geopro/memory/MEMORY.md` for persistent project context.