Cross cube 3D Instance Label Alignment - JamesDarby345/Volumetric_Instance_to_Mesh GitHub Wiki
Purpose:
To synchronize the volumetric label value of the same sheet across cubes. This will make running larger context experiments easier as the same sheet across different cubes will have the same value.
Results:
Before script, each cube uses different label values.
Examples after the script was run, labels that represent the same sheet across cubes are the same value.
How to Use cube_label_reassignment.py:
This script is used to relabel volumetric cube labels so that the same sheets have consistent label values across different cubes.
Usage: python cube_label_reassignment.py [options]
Command Line Arguments
| Argument | Description |
|---|---|
| --vis | Enable visualization for testing purposes. |
| --cube-size CUBE_SIZE | Set the cube size (default: 256). |
| --input-path INPUT_PATH | Specify the path to the directory containing mask files. |
| --output-path OUTPUT_PATH | (Optional) Specify the path to save relabeled mask files. |
| --overwrite | Overwrite existing files instead of appending _relabeled_mask to filenames. |
| --no-filter | Skip running filter_and_reassign_labels before relabeling. |
| --half-winding-plane PLANE | Specify the half-winding plane (e.g., "x:4048"). |
Detailed Argument Descriptions
--vis: When enabled, this flag activates visualization features for testing and debugging purposes. --cube-size: Sets the size of the cubes being processed. Default is 256. --input-path: Specifies the directory containing the mask files to be processed. If not provided, the script uses a default path. --output-path: Optionally specifies a directory to save the relabeled mask files. If not provided, the output will be saved in the same directory as the input files. --overwrite: When this flag is set, the script will overwrite existing files instead of creating new files with _relabeled_mask appended to the filename. --no-filter: By default, the script runs filter_and_reassign_labels on the input files before relabeling. This flag skips that step. --half-winding-plane: Specifies a plane to divide the volume, preventing labels from connecting across this plane. Format is "axis:value" (e.g., "x:4048").
Notes
The script processes NRRD files with the _mask.nrrd suffix in the input directory. By default, it runs filter_and_reassign_labels on the input files before relabeling. The script uses parallel processing to speed up the relabeling process. Errors encountered during processing will be displayed at the end of the script execution.
If the cubes start to form a complete winding, since a scroll is one sheet in reality, this could end up assigning the same label value to each winding which isnt useful. The half winding plane doesnt allow labels to be considered connecting across it if it is used. Ex:
A potential 'failure' case is when a single sheet has two separate pieces in one cube but is connected in another, resulting in 2 different label values still being used in the cube with 2 pieces. I decided to just leave it as is. Ex:
Steps
The main script compares the adjacent faces of all the *_mask.nrrd cubes in the input directory, and assigns the pairs that overlap, and overlap the most to the same label group, which represents a sheet. The datas structure has the group number, and each entry has the cube zyx value and label value for that cube that belongs in that group. This allows for a memory efficient, and scalable representation of the required information. Each cube is relabelled using this map and saved in parallel.
If the no filter flag isnt passed it also removes small disconnected objects from the labels and fixes any erroneous nrrd headers. This step takes awhile (~90 seconds on 60 cubes on M2 macbook pro) but only needs to be run once.