Complete animal-only NPX2 planning, vessels, 3D, and surgery PDF

[KaiCao2003]

Outcome

This PR completes the animal-only Brain3D planning workflow with exactly Dorsal / Coronal / Sagittal / Horizontal / 3D.

Animal research only — non-human and non-clinical. Brain3D is an engineering planning build, not validated surgical navigation, a vessel-clearance system, or a veterinary/clinical device.

Direct NPX2 planning

• The primary selector exposes only NP2003 (1 shank) and NP2013 (4 shanks).
• AP/ML are the surface insertion coordinates of user-facing Shank 1 relative to the source-pinned Pinpoint/Urchin bregma convention.
• AP− is posterior; ML− is animal-left.
• Depth is the positive Shank 1 path length from its local annotation-surface crossing to the distal target.
• Angle is sagittal: positive A→P, negative P→A.
• NP2013 Sagittal makes Shank 1 most anterior; 90° CW from dorsal makes Shank 1 animal-left-most.
• 3D renders every complete 10 mm shaft, including the proximal length outside the brain. Slice traversal and vessel display use only the implanted surface-to-tip segment.
• There is no Apply/Create button. Model/layout changes are atomic and immediate; numeric values commit only on Return or real focus loss, never on a partial keystroke such as the 9 while entering 90.

Atlas, regions, vessels, and PDF

• All 840 Allen ontology entries are searchable. Reviewed geometry highlights in Dorsal, Coronal, Sagittal, Horizontal, and 3D; ontology-only entries remain selected with an explicit no-geometry message.
• VesSAP BL6J-no1 major vessels are visible in every view with an adjustable 30–250 µm display threshold. Capillaries and vessel-clearance claims remain excluded.
• 3D uses a light SceneKit presentation with the selected region, NPX shafts, and radius-bearing vessel tubes.
• Surgery export fills the configured protocol PDF, adds one selected planning view or all five, and appends one coordinate-matched page from the configured 132-page atlas PDF. Source PDF paths persist in Settings and source files are never modified.
• Population density and subject-image registration remain archived compatibility code/state, not primary UI.

Persistence and validation

• Schema 9 adds the calibration-free v4 surface-plan record while preserving legacy v1–v3 packages.
• Validation re-resolves the surface from the pinned Allen 25 µm annotation and reconstructs AP/ML, Shank 1 entry, depth, signed angle, layout, full catalog geometry, hashes, and provenance.
• Viewer and model publications cross a main-turn boundary to avoid SwiftUI view-update mutations.
• CryptoKit digest formatting is Foundation-free; there are no remaining integer String(format:) call sites.

Verification

• Python: 698 passed, 2 intentional skips.
• Ruff format/check, mypy, lockfile, minimal-runtime bridge check, shell syntax, and git diff --check: pass.
• Swift: 252 tests in 40 suites passed.
• Real app QA covered NP2013, both layouts, Return/focus-loss commits, vessel threshold, slice navigation, region selection, and 3D switching. Unified logs contained zero Publishing changes from within view updates events.
• Standalone QA produced a zip containing exactly one Brain3D.app; 261 Mach-O files were arm64-only with maximum deployment target macOS 14.0, valid ad-hoc signature, embedded bridge, licenses, SBOM, and provenance. A fresh clean-main artifact will be rebuilt after merge; the dirty QA zip will not be published.
• The supplied protocol/atlas volumes were unavailable during the final run, so final verification uses synthetic PDF fixtures and does not claim a new export against those external files.

Public release boundary

The release asset is Apple Silicon only and noncommercial because the bundled VesSAP derivative is CC BY-NC 4.0. No Developer ID identity is installed, so the first public build will be ad-hoc signed and not notarized; release notes will state that Gatekeeper may require manual approval.