[codex] Add 3dtrees ForestMamba LAZ wrapper

[kgerb]

Summary

Adds a 3Dtrees-oriented ForestMamba LAZ wrapper and direct bluepoint output path.

• add src/parameters.py and src/run.py as the Galaxy-facing entrypoint, following the thin parameters.py -> run.py shape used by other 3Dtrees tools
• leave GPU assignment to the runtime by default; empty --gpu-device means CUDA_VISIBLE_DEVICES is not set by the wrapper
• keep scripts/forest_mamba_laz_batch.py as the shared implementation engine for LAZ staging, ForestMamba inference, bluepoint pass control, and streamed enriched LAZ writing
• expose bluepoint controls including score threshold, second-pass threshold, and spatial match tolerance
• remove the wrapper-level merge-condition flow and apply direct predictions instead
• normalize final PredInstance_FM values by mapping raw negative instance IDs to 0 while preserving valid ForestMamba IDs
• switch ForestMamba PLY output helpers to chunked binary writes to avoid large Python list-backed arrays
• document the Galaxy wrapper entrypoint and legacy manual PLY flow in the README

Cleanup After Review

The PR was tightened after review:

• removed accidental ForestFormer3D path/name drift in README examples
• restored sync_bn = 'torch' in the expand config; the config now has no diff against main
• removed unrelated manual-query/query-metadata code that had leaked in from local work

Related PRs

Parent repo PR: https://github.com/3dTrees-earth/3dtrees/pull/221

Galaxy wrapper PR: 3dTrees-earth/galaxytools#5

The parent PR adds tools/3dtrees_ForestMamba as a submodule and pins it to this PR branch commit (8b29b31). The Galaxy PR adds tools/3dtrees_forestmamba/forestmamba.xml, which calls this repo's /workspace/src/run.py entrypoint.

Why

3Dtrees needs a SegmentAnyTree-style wrapper for ForestMamba outputs that can write final LAZ products directly and safely for downstream remap/merge tooling. Direct output inspection showed current ForestMamba valid instance IDs already start at 1, so the final export convention is -1 -> 0 and valid IDs preserved.

Fixes 3DT-1194.

Validation

• git diff --check origin/main
• PYTHONPYCACHEPREFIX=/tmp/forestmamba-pycache python -m py_compile scripts/forest_mamba_laz_batch.py src/parameters.py src/run.py oneformer3d/oneformer3d.py
• python src/run.py --help | rg "dataset-path|bluepoint|second-pass|spatial-match|show-params"
• python src/run.py --show-params true confirms empty gpu_device
• python scripts/forest_mamba_laz_batch.py --help | rg "bluepoint|second-pass|spatial-match|output-dir"
• synthetic wrapper probe confirmed src/run.py maps Galaxy-style params into batch args
• earlier synthetic wrapper probe confirmed dense spatial matching and [-1, 0, 1, 7] -> [0, 0, 1, 7]

Notes

This is opened as a draft because it still deserves one full end-to-end ForestMamba wrapper run before production deployment. The Galaxy wrapper PR also notes the current Docker startup blocker encountered during the local mikro.laz run attempt.

[linear-code]

3DT-1194 Normalize ForestMamba instance IDs by mapping raw -1 to 0

Problem

ForestMamba raw predictions use PredInstance_FM = -1 for no assigned instance. Downstream merge/remap tooling expects non-negative instance labels, so final 3dtrees ForestMamba products must not emit negative PredInstance_FM values.

Direct output inspection showed that current ForestMamba valid instances already start at 1 and raw 0 is not used as a tree instance. Therefore the correct export convention is not to shift valid IDs by +1; it is to map raw negative IDs to 0 and preserve existing valid IDs.

Desired convention

• Raw instance_pred < 0 becomes output PredInstance_FM == 0 for no-instance / unassigned.
• Raw valid instance IDs are preserved, so output tree instances remain strictly positive.
• Downstream tools can treat 0 as no-instance and >0 as a valid predicted instance.
• Avoid emitting negative PredInstance_FM values in final 3dtrees ForestMamba products.

Scope

Update the 3dtrees ForestMamba wrapper/export path, especially tools/3dtrees_ForestMamba/scripts/forest_mamba_laz_batch.py, so both whole-file and bluepoint/tiled-style final LAZ writes apply the same normalization.

Acceptance criteria

• Final ForestMamba LAZ products contain no negative values in PredInstance_FM.
• PredInstance_FM == 0 represents no-instance / unassigned points.
• All predicted tree instances have PredInstance_FM > 0 and preserve ForestMamba's valid raw IDs.
• Whole-file and bluepoint wrapper output paths use the same final LAZ convention.
• A focused synthetic check with [-1, 0, 1, 7] verifies the normalized output is [0, 0, 1, 7].
• The wrapper summary documents raw_negative_to_0_valid_preserved.

Review in Linear