Add opt-in read-only vertebral instance analysis

[ShirongZuo-ai]

Summary

Add a disabled-by-default anatomical-consistency audit that produces deterministic per-case JSON reports without modifying segmentation outputs.

This is a diagnostic, read-only contribution. It does not implement automatic vertebral correction, re-identification, or relabeling.

What changed

• Add analyze_vertebral_instances(...), a standalone analyzer that:

  • accepts masks keyed by canonical anatomical names rather than numeric label offsets;
  • derives physical spacing and orientation from the affine;
  • identifies thick-core candidates and estimates a spine trajectory;
  • reports off-trajectory, duplicate, internal-missing, nonmonotonic, mixed, overlapping, partial-FOV, and ambiguous evidence;
  • supports geometry-only operation and optional explicitly authorized CT confidence evidence;
  • returns deterministic JSON-compatible primitives and never returns corrected masks.

• Add an opt-in batch adapter that runs immediately after segmentation loading and before mask combination or organ postprocessing.

• Write one canonical JSON audit to:

  <output_root>/<output_dir_name>/<patient_id>.json
  

• Add strict configuration validation, lazy analyzer import, failure isolation, atomic writes, same-patient concurrency protection, path containment, and control-character rejection.

Configuration

The audit is disabled by default:

vertebrae_instance_analysis:
  enabled: false
  output_dir_name: vertebrae_analysis
  use_reference_as_ct: false

CT data are accessed only when use_reference_as_ct: true. The configured reference must be a known voxel-aligned CT image. Invalid requested CT input falls back to geometry-only evidence with a warning.

Safety and compatibility

• The analyzer does not delete, fill, merge, suppress, or relabel voxels.
• Input masks, CT, and affine values are not mutated.
• The audit result is not used by downstream segmentation processing.
• Absent or disabled configuration creates no audit directory and does not import the analyzer implementation.
• Actual main.main() regression tests verify identical segmentation-output SHA-256 maps for absent, disabled, geometry-only, CT-authorized, and analyzer-failure modes.
• Analyzer and audit-write failures are logged, while segmentation processing continues unchanged.
• Successful reports are atomically replaced from invocation-owned temporary files.
• A failed rerun may leave the most recent successful report intact; logs describe the latest failed attempt.
• Symlinked audit directories are rejected, and the resolved audit directory must remain below the resolved output root.
• Audit files currently retain owner-only permissions inherited from mkstemp.

Validation

PYTHONPYCACHEPREFIX=<fresh_tmp_dir> \
PYTHONDONTWRITEBYTECODE=1 \
python -B -m unittest discover \
  -s tests \
  -p 'test_vertebrae_instance*.py' \
  -v

Result:

Ran 57 tests in 21.741s

OK

• Passed: 57
• Failures/errors: 0
• Skipped: 0
• Warnings: 0

Coverage includes physical spacing and affine behavior, anisotropy, supported mild obliquity, unsupported shear/obliquity, missing and duplicate identities, partial FOV, ambiguity, overlaps, rejected off-trajectory candidates, CT-optional behavior, deterministic serialization, input non-mutation, multiprocessing consistency, actual batch loading/saving, failure handling, concurrent same-patient writes, and symlink containment.

Boundaries and limitations

• Diagnostic thresholds are provisional defaults, not population-validated constants.
• No clinical validation, population-level generalization, or DSC improvement inside ShapeKit is claimed.
• CT alignment and provenance remain caller responsibilities.
• CT affects confidence evidence only and never changes candidate boundaries.
• Transitional anatomy, fractures, implants, severe leakage, merged bodies, and incomplete scans may remain unresolved.
• Thick-core separation is not claimed to be an anatomical intervertebral foreground gap.
• This does not integrate the warm-up V3.1 automatic relabeling pipeline.
• This branch does not import or depend on another open PR and does not activate automatic re-identification.
• Path containment addresses ordinary misconfiguration and concurrent ShapeKit execution; it is not a security claim against hostile local filesystem actors.

Reviewer focus

• Confirm the API remains read-only and returns JSON primitives only.
• Review affine, spacing, trajectory, and thick-core assumptions.
• Review conservative unresolved and partial-FOV behavior.
• Confirm anatomical ordering is name-based rather than numeric-label-based.
• Confirm CT access requires explicit authorization.
• Confirm the batch call occurs before any segmentation mutation.
• Confirm disabled mode preserves legacy output behavior.
• Review canonical JSON, concurrent-write ownership, and path containment.
• Confirm no automatic correction or dependency on another open PR is introduced.