Add Z alignment repair utility (fix_z_align.py)

[msayr]

Motivation

• Provide a targeted tool to repair a problematic Z-alignment boundary without reprocessing or deleting the remainder of a stack.
• Allow users to preview a repaired local range, visually inspect it in Neuroglancer, and then propagate the corrected alignment to the end of the configured stack.

Description

• Add fix_z_align.py, a standalone CLI that accepts a path to an existing align_stack_z JSON config and a single slice or inclusive slice range (formats: N, N:M, or N-M).
• The script realigns a small preview suffix by composing a repair config (adjusting local_z_min, local_z_max, z_offset, first_slice, and enabling overwrite) and calling align_stack_z for the preview and for the final propagation.
• Before rerunning the suffix it invalidates cached MongoDB progress documents that would otherwise cause slices to be skipped by deleting flow_z, render_z (by global_slice), and optionally mesh_relax_z documents for the affected range.
• Supports Neuroglancer preview via existing inspect_dataset, CLI confirmation (y/yes) to proceed, --skip-preview to immediately propagate, --preview-after to extend the preview window, and --project-name to override the config project name.

Testing

• Ran python -m py_compile fix_z_align.py which succeeded to validate basic syntax and imports.
• Ran python fix_z_align.py --help which failed in this environment because importing OpenCV triggers ImportError: libGL.so.1: cannot open shared object file due to a missing system library, so Neuroglancer/preview execution could not be exercised here.
• No further automated tests were executed in this container; runtime behavior (preview + MongoDB deletion + suffix propagation) was implemented to reuse existing alignment and DB utilities in the codebase.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 68128d638d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Allow repaired stacks to bypass z_aligned skip

In the normal use case this tool repairs a stack that has already been processed, so the input store already has z_aligned=True; align_stack_z returns immediately in that case unless wipe_progress_flag is true (checked in emalign/scripts/align_stack_z.py). Because the repair config always forces this flag to False, both the preview and final propagation calls become no-ops after deleting progress documents, leaving the bad alignment unrepaired.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve reference-based configs' unset first_slice

When the original config uses reference_path, align_stack_z expects first_slice to stay None; otherwise it passes both an external reference dataset and an external first slice into the flow code, which raises the incompatible-reference error in emalign/align_z/align_z.py. Unconditionally setting first_slice here therefore makes repairs fail for reference-aligned stacks instead of continuing to align slices against the reference volume.

Useful? React with 👍 / 👎.