Add registration-based particle initialization - #2615
Open
akenmorris wants to merge 7 commits into
Open
Conversation
Spread particles over a single reference shape and carry them onto the other shapes with deformable registration, instead of splitting on all shapes at once. This is not a general replacement for splitting. It is for anatomy complex enough that splitting fails to converge to a usable correspondence. A registration costs far more than a split, so on shapes where splitting already works this is slower with nothing to show for it. Turned on by ticking "Registration Initialization" in the Studio optimize panel, or by setting the `initialization_mode` optimize parameter of a project file to `registration`. The reference shape is picked automatically; set `initialization_reference` to choose one. New Libs/Image/ImageRegistration follows the ANTs SyNRA pipeline (rigid, affine, SyN) over distance transforms, using the same multi-resolution schedule. Its accuracy matches antspyx on the same inputs. On an internal cohort where splitting does not produce a usable model, this improves generalization roughly threefold over split initialization. Also available as `shapeworks transfer-particles` and as a Python binding.
A registration depends only on the pair of shapes and the registration settings, and on none of the optimization parameters. Caching the computed transforms lets the particle count, iteration counts and weightings be changed and the model rebuilt without registering the same shapes again. Enabled by default; set the `registration_cache` optimize parameter to false to turn it off. Transforms are kept in a `registration_cache` directory beside the project rather than under the particle output, which carries the optimize prefix and so would change with the very parameters this is meant to be insensitive to. Entries are named by everything the transform depends on, including the size and timestamp of each groomed input, so regrooming invalidates them. The displacement field is stored as a separate compressed image of floats rather than inside the transform file as raw doubles, which halves it. It is stored at full resolution: halving it in each dimension is eight times smaller again, but costs a sixth of the registration's own accuracy. On a three shape cohort this takes a re-run from 74s to 11s, with bit identical particles.
- Show progress during the transfer phase and refresh Studio between registrations, which run no optimizer iterations and so previously left the last spreading message frozen on screen. - Build the reference image lazily, only on a real cache miss, so a fully cached re-run no longer rasterizes it (transfer phase drops to a fraction of a second). - Show the registration band as an empty "auto" field rather than 0, and accept it as valid so it no longer blocks the optimize button.
New `registration_grid_size` optimize parameter sets the rasterization resolution for mesh registration (voxels across the largest dimension, default 128). Lower is faster and coarser; higher is finer at cubic cost. Affects mesh domains only; image inputs already have a resolution. The auto band is now a fixed physical width (5% of the shape's largest dimension), independent of the grid. Previously it was a fixed number of voxels of the chosen grid, so a finer grid silently narrowed the band and starved the similarity metric of context, which made finer grids register dissimilar shapes worse rather than better. Decoupled, the grid controls only resolution: at a detailed test pair, grid 192 improved from 2.37mm to 1.34mm of surface-match error. (The wider band improves raw registration fidelity; the downstream optimization largely absorbs it, so final model quality on the tested cohort is unchanged.) The grid size is included in the registration cache key, since it changes the transform. Also exposed in the Studio optimize panel next to the band, and documented as a speed/detail tradeoff.
akenmorris
force-pushed
the
amorris/reg-init
branch
from
August 4, 2026 07:42
4e13e5c to
7492d3c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #2374
Alternative to particle splitting: spread particles over a single reference shape, then carry them onto every other shape by deformably registering the reference to it (ANTs SyNRA stages: rigid -> affine -> SyN over distance transforms). Each shape starts optimization already holding a full set of corresponding particles.