[codex] Document straightened TIFF annotation metadata

[den-sq]

Summary

• document annotation_points as [x, y, z] straightened-volume coordinates
• add producer-side regression coverage that annotation_points is included in the existing straightened TIFF metadata kwargs
• preserve the existing TIFF writer metadata shape; this PR no longer changes slice_parallel_pipeline.py behavior

Producer-side documentation/coverage for ChengLabResearch/ouroboros_autoseg_plugin#19.
Paired with ChengLabResearch/ouroboros_autoseg_plugin#27, which owns the cross-repo Rust consumer contract.

Validation

• PYTHONPATH=python /home/dnorthover/miniconda3/envs/lftomo/bin/python -m pytest python/test/pipeline/test_straightened_tiff_metadata.py
• git -C ouroboros diff --check

[tavateva]

Draft Promotion Review ⚠️ CONDITIONALLY BLOCKED

Reviewed against Draft Promotion Criteria.

Special case: Issue #19 is cross-repo; accepting that producer and consumer sides can be separate PRs.

Criterion Assessment

1. CI and mergeability: ⚠️ AMBIGUOUS — Mergeable, 2 checks (status not detailed in review)
2. Issue Acceptance Criteria: ⚠️ PARTIAL SCOPE ACCEPTED — This PR addresses producer side (Ouroboros); consumer side (plugin) in paired PR Cannot Backproject from Compressed Image #27. Partial implementation acceptable if both PRs are tracked to completion.
3. PR body Test Plan checkboxes: ✅ PASS — Producer-side test (test_straightened_tiff_metadata.py) executed and passed
4. Tests run: ✅ PASS (producer side) — Producer-side metadata test executed; consumer-side deferred to paired PR Cannot Backproject from Compressed Image #27
5. Scope: ✅ PASS (revised) — Producer-side documentation and regression coverage; acceptable as partial cross-repo implementation
6. Regressions: ✅ PASS (producer side) — Producer-side tested and passing
7. Judgement calls: ✅ PASS — Producer/consumer split is reasonable for cross-repo contracts

VERDICT: ⚠️ CONDITIONALLY BLOCKED

Remaining Concerns

Primary consideration: Paired consumer PR #27 (ChengLabResearch/ouroboros_autoseg_plugin) is still DRAFT.

Two approaches:

Approach 1 (atomic merge): Hold both PRs until consumer PR #27 exits draft, then promote/merge both together. This ensures the full cross-repo contract is validated before either side merges.

Approach 2 (sequential merge): Merge producer-side (this PR) first, leave issue #19 open, merge consumer PR #27 when ready, then close issue #19. Producer changes are backward-compatible (adds metadata, doesn't remove), so this is safe.

Recommendation

Accept Approach 2 if:

• Producer changes don't break existing consumers (backward compatible)
• Issue v1.1.0 Bump #minor #19 clearly tracks that consumer PR Cannot Backproject from Compressed Image #27 is still needed
• Consumer PR Cannot Backproject from Compressed Image #27 references this PR for context

Require Approach 1 if:

• Contract changes could break without both sides present
• Atomic deployment is needed for safety

Based on the PR body stating this "preserves the existing TIFF writer metadata shape" and only adds documentation/regression coverage, Approach 2 appears safe.

Issue #19 Tracking

If this PR is promoted as producer-side implementation:

• ✅ Document annotation_points metadata (this PR)
• ✅ Add producer-side regression coverage (this PR)
• ⏳ Consumer-side Rust contract validation (PR Cannot Backproject from Compressed Image #27, still draft)
• ⏳ End-to-end cross-repo test (deferred until PR Cannot Backproject from Compressed Image #27 ready)

Recommend: Promote this PR, keep issue #19 open, track consumer PR #27 to completion.