diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 7005c46f8fe..c872c6d5051 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -1,6 +1,35 @@ # Release Notes +## ShapeWorks 6.7.0 + +### What is new? + + * **ShapeWorks Back-end** + * Fixed domain optimization speedups: shape space precomputation, Procrustes caching, and batch particle loading + * PCA projection correspondence for fixed domain optimization (`use_pca_projection` parameter) + * Automatic mesh repair in grooming pipeline (replaces manual Extract Largest Component step) + * Auto ICP alignment subset size defaults to 30 shapes for faster grooming on large datasets + * Support for multiple shared boundaries between domains + * Early stopping via morphological deviation score for optimization convergence detection + * DeepSSM CLI: `shapeworks deepssm` command for headless/batch DeepSSM workflows + * Laplacian mesh warping as alternative to biharmonic, reducing thinning artifacts on sparse regions + * Built-in performance profiling and Chrome trace output via `SW_TIME_PROFILE` and `SW_TIME_TRACE` environment variables (see [developer docs](../dev/build.md#performance-profiling)) + + * **ShapeWorks Front-end** + * DWD (Distance Weighted Discrimination) group analysis method alongside LDA + * Redesigned Optimize panel + * Export clipped meshes + * Warp method selector (Biharmonic/Laplacian) in Analysis panel + + * **Platform Updates** + * Python 3.12 + * VTK 9.5.0 + * ITK 5.4.4 + * PyTorch 2.8.0 (2.2.2 on Intel Mac) + * Linux builds use manylinux_2_28 (GLIBC 2.28, compatible with RHEL 8+, Ubuntu 20.04+) + + ## ShapeWorks 6.6.1 - 2025-05 ### Fixes diff --git a/docs/deep-learning/deep-ssm.md b/docs/deep-learning/deep-ssm.md index 006cfaca2b4..f9c2c73e30b 100644 --- a/docs/deep-learning/deep-ssm.md +++ b/docs/deep-learning/deep-ssm.md @@ -64,6 +64,72 @@ We then compare the original mesh to the predicted mesh via surface-to-surface d ![Mesh Distance](../img/deep-learning/mesh-distance.png) +## DeepSSM CLI + +The `shapeworks deepssm` command runs the full DeepSSM pipeline from the command line, without requiring Studio. This enables headless execution on HPC clusters and servers, batch processing of multiple projects, and integration with shell scripts and automated workflows. + +### Command Syntax + +```bash +shapeworks deepssm [options] +``` + +The project file (`.xlsx` or `.swproj`) must contain both image and shape columns (e.g., `shape_la`, `image_mri`), along with DeepSSM parameters such as data split percentages, augmentation settings, and training configuration. These are the same parameters configurable in the [DeepSSM Studio module](../studio/deepssm-in-studio.md). + +### Options + +| Option | Description | +|--------|-------------| +| `--name ` | Path to project file (alternative to positional argument) | +| `--all` | Run all four steps: prep, augment, train, test | +| `--prep ` | Run preparation. Steps: `all`, `groom_training`, `optimize_training`, `optimize_validation`, `groom_images` | +| `--augment` | Run data augmentation | +| `--train` | Run model training | +| `--test` | Run testing/inference | +| `--num_workers ` | Number of PyTorch data loader workers (default: 0) | +| `--aug_processes ` | Number of augmentation processes (default: 0 = use all cores) | + +If none of `--prep`, `--augment`, `--train`, `--test`, or `--all` are specified, all four steps are run by default. + +### Examples + +Run the full pipeline: + +```bash +shapeworks deepssm my_project.swproj --all +``` + +Run only preparation and augmentation: + +```bash +shapeworks deepssm my_project.swproj --prep all --augment +``` + +Run just training and testing with 4 data loader workers: + +```bash +shapeworks deepssm my_project.swproj --train --test --num_workers 4 +``` + +Run a single prep sub-step: + +```bash +shapeworks deepssm my_project.swproj --prep groom_training +``` + +### Pipeline Steps + +The four steps correspond to the same stages available in [DeepSSM in Studio](../studio/deepssm-in-studio.md): + +1. **Prep** — Grooms and optimizes training shapes, generates validation particles using fixed domains, and prepares images. The `--prep` flag accepts a sub-step to run only part of the preparation. +2. **Augment** — Generates synthetic training data via PCA-based data augmentation. Use `--aug_processes` to control parallelism. +3. **Train** — Trains the DeepSSM network (Base-DeepSSM or TL-DeepSSM depending on project settings). Use `--num_workers` to set PyTorch data loader parallelism. +4. **Test** — Runs inference on the test set and evaluates predicted shapes against ground truth. + +### Configuring DeepSSM Parameters + +All DeepSSM parameters (data split, augmentation count, network architecture, TL-DeepSSM settings, fine-tuning, etc.) are stored in the project file. These can be configured in Studio before running via the CLI, or set programmatically using the ShapeWorks Python API. See the [training configuration parameters](#config-file-parameter-descriptions) section below for details on available settings. + ## Using the DeepSSM Python Package The ShapeWorks DeepSSM package, `DeepSSMUtils`, is installed with the rest of the ShapeWorks Anaconda environment using `install_shapeworks`. diff --git a/docs/dev/build.md b/docs/dev/build.md index 195903a3829..ff6f4809577 100644 --- a/docs/dev/build.md +++ b/docs/dev/build.md @@ -212,4 +212,56 @@ After cmake the Visual Studio solution can be opened with `start ShapeWorks.sln` !!! important "RelWithDebInfo only" Currently it's only possible to build **RelWithDebInfo** on Windows. - + + +## Performance Profiling + +ShapeWorks includes a built-in profiling and tracing framework for diagnosing performance issues. It is controlled via environment variables and has zero overhead when disabled. + +### Environment Variables + +| Variable | Description | +|----------|-------------| +| `SW_TIME_PROFILE=on` | Enable flat profiling. Writes a summary report to `profile.txt` at shutdown with exclusive/inclusive times, call counts, and per-call averages, grouped by thread. | +| `SW_TIME_TRACE=on` | Enable Chrome trace format output. Writes `trace.json` which can be loaded in `chrome://tracing` or [Perfetto](https://ui.perfetto.dev/) for a timeline visualization. | + +Both can be enabled simultaneously. + +### Example + +```bash +SW_TIME_PROFILE=on SW_TIME_TRACE=on shapeworks optimize --name project.swproj +``` + +After the run completes, `profile.txt` will contain a flat profile like: + +``` + %Time Exclusive Inclusive #Calls #Child Exclusive Inclusive Name + total ms total ms ms/call ms/call +------------------------------------------------------------------------------------------------------ + 95.2 8523 12041 128 0 67 94 Optimize::RunOptimize + ... +``` + +And `trace.json` can be loaded in a trace viewer for a timeline of all timed scopes. + +### Adding Instrumentation + +Use the macros from `Profiling.h` to instrument code: + +```cpp +#include + +void MyFunction() { + TIME_SCOPE("MyFunction"); // automatically times the enclosing scope + // ... work ... +} +``` + +Or for manual start/stop: + +```cpp +TIME_START("loading meshes"); +// ... work ... +TIME_STOP("loading meshes"); +``` diff --git a/docs/img/studio/studio_dwd.png b/docs/img/studio/studio_dwd.png new file mode 100644 index 00000000000..9a0c3b7f134 Binary files /dev/null and b/docs/img/studio/studio_dwd.png differ diff --git a/docs/img/studio/studio_export_menu.png b/docs/img/studio/studio_export_menu.png index f99b0b17db2..f1d78c0a5d7 100644 Binary files a/docs/img/studio/studio_export_menu.png and b/docs/img/studio/studio_export_menu.png differ diff --git a/docs/img/studio/studio_optimize.png b/docs/img/studio/studio_optimize.png index e92c1560132..018afffd66a 100644 Binary files a/docs/img/studio/studio_optimize.png and b/docs/img/studio/studio_optimize.png differ diff --git a/docs/new/ai-assisted-segmentation.md b/docs/new/ai-assisted-segmentation.md index 1a5e92936b1..d0d9d007b7e 100644 --- a/docs/new/ai-assisted-segmentation.md +++ b/docs/new/ai-assisted-segmentation.md @@ -5,8 +5,8 @@ [`Medical Open Network for AI (MONAI) Label`](https://monai.io/) is a deep learning framework designed for efficient annotation and segmentation of medical images. -## What’s New? -ShapeWorks Studio now integrates MONAI Label, enabling seamless access to fully automated and interactive deep learning models for segmenting radiology images across various modalities. +## Overview +ShapeWorks Studio integrates MONAI Label, enabling seamless access to fully automated and interactive deep learning models for segmenting radiology images across various modalities. For a detailed demo and step-by-step instructions on using MONAI Label within ShapeWorks Studio, refer to the following guide: diff --git a/docs/new/new-studio.md b/docs/new/new-studio.md index 85f40b9d63a..112630064ab 100644 --- a/docs/new/new-studio.md +++ b/docs/new/new-studio.md @@ -1,9 +1,9 @@ -# New in ShapeWorks Studio 6.2 +# Studio Feature Highlights ## DeepSSM in Studio -New in ShapeWorks 6.2, we have added the ability to run DeepSSM tools in ShapeWorks Studio. +ShapeWorks Studio includes the ability to run DeepSSM tools directly. ![Studio DeepSSM - Augmentation](../img/studio/studio_deepssm_aug2.png){: width="600" } @@ -11,7 +11,7 @@ See [DeepSSM in Studio](../studio/deepssm-in-studio.md) for more information. ## Multiple Domain Alignments -New in ShapeWorks 6.2, we have added support for multiple alignment strategies in ShapeWorks Studio. This allows analysis with and without articulation with a choice of reference domain, or global alignment. +ShapeWorks Studio supports multiple alignment strategies, allowing analysis with and without articulation with a choice of reference domain, or global alignment.

@@ -19,7 +19,7 @@ See [Multiple Domain Alignments](../studio/multiple-domains.md#multiple-domain-a ## Shape Evaluation Charts -New in ShapeWorks 6.2, we have added new shape evaluation charts. Charts for Compactness, Specificity and Generalizaion are provided. +ShapeWorks Studio provides shape evaluation charts for Compactness, Specificity and Generalization. See [Studio Metrics Panel](../studio/getting-started-with-studio.md#metrics-panel) for more information. @@ -28,13 +28,13 @@ See [Studio Metrics Panel](../studio/getting-started-with-studio.md#metrics-pane ## Usability Features ### Group p-value Display -New in ShapeWorks 6.2, Studio has the ability to view group-wise p-values for surface differences. +Studio can display group-wise p-values for surface differences. ![Studio DeepSSM - Group p-value](../img/studio/studio_group_pvalue.png){: width="600" } ### Scalar range controls -New in ShapeWorks 6.2, Studio feature maps, p-value displays, deepssm surface error displays allow for manual control over scalar colormap values. +Studio feature maps, p-value displays, and DeepSSM surface error displays allow for manual control over scalar colormap values.

@@ -82,11 +82,9 @@ Multiple sources of crashes during mesh warping have been fixed and the overall --- -# New in ShapeWorks Studio 6.1 - ## Multiple Domains -As of ShapeWorks 6.1, we added support in ShapeWorks Studio for modeling multiple domains (e.g. anatomies) in joint correspondance model. +ShapeWorks Studio supports modeling multiple domains (e.g. anatomies) in a joint correspondence model. ![ShapeWorks Project with Multiple Domains - Analyze](../img/studio/studio_multiple_domain_analyze.png) @@ -94,7 +92,7 @@ See [Multiple Domains](../studio/multiple-domains.md) for more information. ## Mesh Grooming -As of ShapeWorks 6.1, we added support in ShapeWorks Studio for mesh grooming, including smoothing, hole filling, and iterative closest point pre-alignment. +ShapeWorks Studio supports mesh grooming, including smoothing, hole filling, and iterative closest point pre-alignment. ![ShapeWorks Studio Groom Module for Meshes](../img/studio/studio_groom.png){: width="300" } @@ -102,7 +100,7 @@ See [Groom Module](../studio/getting-started-with-studio.md#groom-module) for mo ## Mesh Support -As of ShapeWorks 6.0, we added mesh support to ShapeWorks Studio including loading meshes, optimizing shape models directly on meshes, and visualizing meshes with scalar feature values. Meshes can store values at vertices such as "cortical thickness", or "fibrosis” and ShapeWorks Studio uses them in a similar manner as feature maps/volumes. +ShapeWorks Studio supports loading meshes, optimizing shape models directly on meshes, and visualizing meshes with scalar feature values. Meshes can store values at vertices such as “cortical thickness” or “fibrosis”, which Studio uses in a similar manner as feature maps/volumes. *Open meshes in Studio* ![Screenshot showing open meshes in Studio](../img/new/open-mesh-studio.png) @@ -119,7 +117,7 @@ We also added a new surface reconstruction method with support for both mesh or ## Improved Studio Interface -As of ShapeWorks 6.0, we added support for automatic glyph sizing, draging/dropping of images and meshes. Scalar bar color is now opposite of background color (e.g., when background is white, text should be dark) (user request). +ShapeWorks Studio supports automatic glyph sizing and drag/drop of images and meshes. Scalar bar color is opposite of the background color for better contrast. *Samples names color is opposite of the background color for a better contrast* ![Studio background](../img/new/studio-background.png) diff --git a/docs/new/shapeworks-command.md b/docs/new/shapeworks-command.md index ff6c60614cc..78d64e91838 100644 --- a/docs/new/shapeworks-command.md +++ b/docs/new/shapeworks-command.md @@ -1,64 +1,37 @@ # ShapeWorks Command -ShapeWorks was a conglomeration of independent executables for grooming and optimization with a GUI (ShapeWorks Studio) for analysis and visualization. This design is highly inflexible, task specific, and poorly documented, and Studio duplicated a significant portion of their functionality. - -We have made significant efforts in organizing the codebase based on functionalities, implementing them as libraries rather than executables to provide a common backbone to command-line and GUI-based tools, and syncing ShapeWorks Studio to use the same underlying libraries. - - -To retain command line usage, we have created a single [`shapeworks`](../tools/ShapeWorksCommands.md) command with subcommands exposing this functionality along with greater flexibility and interactive `--help` for each subcommand.  - -This consolidation makes the framework more powerful and flexible. It also enables ShapeWorks functionality to be used as libraries linked to new applications. - -All the executables used for the segmentation-driven grooming have been consolidated, documented, tested against the original command line tools, and functionally debugged - -Comprehensive unit testing is implemented and executed as part of automatic validation run with each addition to the code. This also serves as independent examples of its use +ShapeWorks provides a single [`shapeworks`](../tools/ShapeWorksCommands.md) command with subcommands for grooming, optimization, and other operations. Each subcommand has interactive `--help` documentation. +The codebase is organized as shared libraries rather than independent executables, providing a common backbone for both command-line and GUI-based tools. This also enables ShapeWorks functionality to be linked into new applications. ## Example: ResampleVolumesToBeIsotropic !!! note "Old command-line: `ResampleVolumesToBeIsotropic `" ``` - ./ResampleVolumesToBeIsotropic --inFilename --outFilename - --isoSpacing + ./ResampleVolumesToBeIsotropic --inFilename --outFilename + --isoSpacing [--isBinaryImage] [--isCenterImageOn] ``` - - -**Disadvantages of the old command-line tool:** - -- Cannot be used by other classes or other APIs or other functions -- Not adaptable (need to edit script files to customize it) -- Each command needs to be given input and output paths -- Creates IO bottlenecks -- Fixed parameters cannot be changed (e.g., num iterations for binarization) -- All logic is buried behind a single command line tool ### Resampling images -!!! note "Old command-line: `ResampleVolumesToBeIsotropic` (for images)" +!!! important "Command-line: `isoresample` (for images)" ``` - ./ResampleVolumesToBeIsotropic --inFilename --outFilename - --isoSpacing - --isCenterImageOn - ``` - -!!! important "New command-line: `isoresample` (for images)" - ``` - shapeworks readimage --name recenter - isoresample --isospacing + shapeworks readimage --name recenter + isoresample --isospacing writeimage --name - ``` + ``` !!! important "C++ (without chaining): `isoresample` (for images)" ```c++ - Image img(); - img.recenter(); - img.isoresample(); + Image img(); + img.recenter(); + img.isoresample(); img.write(); ``` - + !!! important "C++ (with chaining): `isoresample` (for images)" ```c++ Image img().recenter().isoresample().write(); @@ -69,50 +42,34 @@ Comprehensive unit testing is implemented and executed as part of automatic vali ### Resampling segmentations -!!! note "Old command-line: `ResampleVolumesToBeIsotropic` (for segmentations)" - ``` - ./ResampleVolumesToBeIsotropic --inFilename --outFilename - --isoSpacing - --isBinaryImage --isCenterImageOn - ``` - -The old executable’s functionalities are broken down further to make it more modular: - -- Antialias using `shapeworks antialias`  -- Recenter using `shapeworks recenter` -- Binarize using `shapeworks binarize` - - -**Advantages for the new shapeworks API:** +The resampling functionalities are broken down into modular subcommands: -- Promotes user’s understanding of the underlying functionality (more transparency and equivalent simplicity) -- Allows the user to choose the set of commands to be run -- User can know what parameters are considered to perform each command -- User can modify parameter values each step of the way -- User can save/visualize intermediate outputs for troubleshooting +- Antialias using `shapeworks antialias` +- Recenter using `shapeworks recenter` +- Binarize using `shapeworks binarize` +This allows the user to choose the set of commands to run, modify parameters at each step, and save intermediate outputs for troubleshooting. -!!! important "New command-line: `isoresample` (for segmentations)" +!!! important "Command-line: `isoresample` (for segmentations)" ``` - shapeworks readimage --name - recenter antialias --iterations - isoresample --isospacing binarize + shapeworks readimage --name + recenter antialias --iterations + isoresample --isospacing binarize writeimage --name - ``` + ``` !!! important "C++ (without chaining): `isoresample` (for segmentations)" ```c++ - Image img(); - img.recenter(); - img.antialias(); - img.isoresample(); - img.binarize(); + Image img(); + img.recenter(); + img.antialias(); + img.isoresample(); + img.binarize(); img.write(); ``` - -!!! important "C++ (with chaining): `isoresample` (for images)" - ```c++ - Image img().recenter().antialias().isoresample().binarize().write(); +!!! important "C++ (with chaining): `isoresample` (for segmentations)" + ```c++ + Image img().recenter().antialias().isoresample().binarize().write(); ``` -![Isoresampling for segmentations](../img/new/isoresample_seg.png) \ No newline at end of file +![Isoresampling for segmentations](../img/new/isoresample_seg.png) diff --git a/docs/new/shapeworks-python.md b/docs/new/shapeworks-python.md index f6a90f4dcc4..d239c79a518 100644 --- a/docs/new/shapeworks-python.md +++ b/docs/new/shapeworks-python.md @@ -2,7 +2,7 @@ !!! important "ShapeWorks with Python support" - ShapeWorks Python library is currently under active development and is part of our major releases as of **ShapeWorks 6**. + The ShapeWorks Python library is included with all ShapeWorks releases. There is no one-size-fits-all when it comes to grooming your data for shape modeling. Instead, there are general guidelines that one could consider when deciding on his/her own workflow. diff --git a/docs/studio/multiple-domains.md b/docs/studio/multiple-domains.md index 6a8f28aad98..c861320fe7e 100644 --- a/docs/studio/multiple-domains.md +++ b/docs/studio/multiple-domains.md @@ -50,6 +50,6 @@ In the presence of multiple anatomies, there are multiple alignment strategies t Below is an example of these four options with a pelvis and femur model. -

+

For a detailed explanation of alignment options, Multi-Level Component Analysis (MCA), their interactions, and how they affect group p-values, see [Multi-Domain Reference Frames](multi-domain-analysis-reference-frames.md). diff --git a/docs/studio/studio-analyze.md b/docs/studio/studio-analyze.md index 2500d8aa89d..dc56596023d 100644 --- a/docs/studio/studio-analyze.md +++ b/docs/studio/studio-analyze.md @@ -14,30 +14,39 @@ The Group mode allows for group comparison to quantify and visualize population- ![ShapeWorks Studio Analysis View Panel Group Display](../img/studio/studio_analyze_view_group.png) -There are three different group analysis options available: +There are four different group analysis options available: -* LDA -* Group Particle P-Values -* Network Analysis +* **LDA** — Linear Discriminant Analysis finds the direction that best separates two groups by maximizing between-group variance relative to within-group variance. +* **DWD** — Distance Weighted Discrimination is a robust alternative to LDA that performs better in high-dimensional, small-sample settings common in shape modeling. +* **Group Particle P-Values** — Computes per-particle p-values between groups, highlighting regions of statistically significant shape difference. +* **Network Analysis** — Uses cluster-based statistical methods to identify spatially connected regions of significant group differences on the shape surface. + +Both LDA and DWD produce a chart showing probability density functions (PDFs) for each group projected onto the discriminant direction, along with individual shape mappings as scatter points. This visualization helps assess how well the shape model distinguishes between populations. ### LDA -Selecting LDA from the analysis method dropdown will generate an LDA chart based on the two groups: +Linear Discriminant Analysis (LDA) finds the linear direction in PCA space that best separates two groups by maximizing between-group variance relative to within-group variance. ![ShapeWorks Studio LDA Chart](../img/studio/studio_lda.png){: width="300" } +### DWD + +Distance Weighted Discrimination (DWD) finds a separating hyperplane that maximizes the average inverse distance of each sample to the boundary. This makes DWD more robust than LDA in high-dimensional, small-sample settings — a common scenario in shape modeling where the number of PCA modes can exceed the number of subjects. Each group requires at least 2 samples. + +![ShapeWorks Studio DWD Chart](../img/studio/studio_dwd.png){: width="300" } + ### Group Particle P-Values -Performs per particle p-value computation for each group. +Computes a p-value for each correspondence particle to identify where two groups differ significantly in shape. For each particle, a Hotelling T-squared test compares the 3D positions across subjects in both groups. The test is repeated over multiple random subsamples (permutations) and the resulting p-values are corrected for multiple comparisons using false discovery rate (FDR) correction. Particles with low p-values indicate regions where the two groups have statistically significant shape differences. The p-values are displayed as a colormap on the shape surface. ![ShapeWorks Studio Group Particle P-Value](../img/studio/studio_analyze_group_pvalue.png){: width="300" } ### Network Analysis -![ShapeWorks Studio Network Analysis](../img/studio/studio_network_analysis.png){: width="300" } - The Network Analysis tool provides a method to statistically analyze data captured in feature maps. Two implementations have been included: Network Analysis and SPM1D. Statistical parametric mapping (SPM, https://www.fil.ion.ucl.ac.uk/spm/) was introduced for the analysis of brain imaging data and has since been used in statistical analysis of surface-based group differences. The SPM1D option uses this technique without consideration of the connectivity and spatial relationship of the input data. The Network Analysis method uses the relative size of the network of connected correspondence particles to identify significant differences amongst groups, as originally described by Forman and colleagues (Forman SD, et al. Magnetic Resonance in Medicine33:636-647, 1995). Our publication on the specifics of this method and example applications is in review and will be referenced here when available. +![ShapeWorks Studio Network Analysis](../img/studio/studio_network_analysis.png){: width="300" } + | Option | Description | |-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Feature Map | Choose which feature to operate on. | diff --git a/docs/studio/studio-export.md b/docs/studio/studio-export.md index c0ed1a8ebd9..c7c8f2963da 100644 --- a/docs/studio/studio-export.md +++ b/docs/studio/studio-export.md @@ -5,6 +5,7 @@ The File -> Export menu is shown below. ![ShapeWorks Studio Export Menu](../img/studio/studio_export_menu.png){: width="200" } * Export Current Mesh - Export the current mesh as a VTK mesh file +* Export Current Mesh Clipped - Export the current mesh with cutting plane constraints applied. Also available via right-click on a shape. * Export Current Particles - Export the currently display particles as an "X Y Z" particles file * Export Current Particle Scalars - Export the currently displayed particle scalars as a CSV file * Export Current Mesh Scalars - Export the currently displayed mesh scalars as a CSV file diff --git a/docs/studio/studio-groom.md b/docs/studio/studio-groom.md index 580e11ff80b..4b8d03dbd3e 100644 --- a/docs/studio/studio-groom.md +++ b/docs/studio/studio-groom.md @@ -22,6 +22,8 @@ Image Grooming Parameters Mesh Grooming Parameters +Before the mesh grooming pipeline runs, each mesh is automatically repaired. This includes triangulation, extraction of the largest connected component, removal of duplicate points and degenerate cells, non-manifold geometry fixes, and removal of zero-area triangles. + | Parameter | Description | | --- | ----------- | | Fill Holes | Fill small holes in the mesh | @@ -39,4 +41,5 @@ Alignment Parameters | Parameter | Description | | --- | ----------- | | Reflect | Option to reflect some shapes over a given axis if a given column matches a given value (e.g. reflect 'side' over 'Y' if 'left') | -| Alignment | Option to align with centering (center of mass), iterative closest point (translation and rotation), or landmarks (best fit, when specified) | \ No newline at end of file +| Alignment | Option to align with centering (center of mass), iterative closest point (translation and rotation), or landmarks (best fit, when specified) | +| Alignment Subset Size | Number of shapes to use when selecting the reference shape for ICP alignment. Default is auto (-1), which uses a subset of 30 to avoid expensive pairwise comparisons on large datasets. Set to 0 to use all shapes. | \ No newline at end of file diff --git a/docs/studio/studio-optimize.md b/docs/studio/studio-optimize.md index d389d668292..228ccf98ac0 100644 --- a/docs/studio/studio-optimize.md +++ b/docs/studio/studio-optimize.md @@ -15,14 +15,21 @@ Optimization Parameters | Ending Regularization | Sets the ending regularization value. See details about regularization [here](../workflow/optimize.md#starting-and-ending-regularization) | | Iterations per Split | The number of iterations in the initialization step for each split (i.e., scale) | | Optimization Iterations | Number of iterations for each optimization step. | -| Geodesic Distance | Enable the use of geodesic distance for particle to particle interactions. This is much slower, but can help with some complex structures/ | +| Narrow Band | Number of voxels surrounding zero level for distance transform based optimizations. Normally a value of 4 is sufficient | +| Geodesic Distance | Enable the use of geodesic distance for particle to particle interactions. This is much slower, but can help with some complex structures | +| Geodesic Remesh Percent | Percentage of vertices to use when remeshing for geodesic computation (default: 100). Lower values speed up geodesic calculations | | Normals | Enable the use of surface normals as a correspondence feature | -| Normals Strength | Amount to scale surface normals feature to give it enough weight relative to XYZ. | -| Procrustes | Enable use of procrustes registration as part of optimization | -| Procrustes Scaling | Enable scaling as part of procrustes to remove overall scale from the model | -| Procrustes Rotation/Translation| Enable procrustes rotation/translation to remove translation/rotation from the model | -| Procrustes Interval | Interval of iterations to run procrustes | +| Normals Strength | Amount to scale surface normals feature to give it enough weight relative to XYZ | +| Geodesic from Landmarks | Compute geodesic distance fields from landmarks and use as a correspondence attribute | +| Geodesic Landmarks Weight | Weight for the geodesic-from-landmarks correspondence term (default: 1.0) | | Multiscale Mode | Enable multiscale optimization where each particle split level after the multiscale start number runs in both initialization and optimization modes | -| Multiscale Start | Number of particles to begin multscale mode | +| Multiscale Start | Number of particles to begin multiscale mode | +| Shared Boundary | Enable shared boundary correspondence for multi-domain models with shared surfaces | +| Shared Boundary Weight | Weight for the shared boundary correspondence term (default: 0.5) | | Use Initial Landmarks | Enable the use of landmarks as starting particles | -| Narrow Band | Number of voxels surrounding zero level for distance transform based optimizations. Normally a value of 4 is sufficient | \ No newline at end of file +| Procrustes | Enable use of Procrustes registration as part of optimization | +| Procrustes Interval | Interval of iterations to run Procrustes | +| Procrustes Scaling | Enable scaling as part of Procrustes to remove overall scale from the model | +| Procrustes Rotation/Translation | Enable Procrustes rotation/translation to remove translation/rotation from the model | +| Sampling Scale | Enable per-domain particle density scaling for multi-domain models. When Auto Scale is checked, the multiplier is computed automatically based on domain surface areas | +| Sampling Scale Multiplier | Multiplier for particle sampling density scaling (used when Auto Scale is unchecked) | \ No newline at end of file diff --git a/docs/studio/using-constraints.md b/docs/studio/using-constraints.md deleted file mode 100644 index a5678e988da..00000000000 --- a/docs/studio/using-constraints.md +++ /dev/null @@ -1,52 +0,0 @@ - -# Using Constraints in Studio - -ShapeWorks Studio supports grooming, optimization and analysis of shapes with constraints, i.e. explicit inclusion and exclusion areas of the surfaces. These constraints can be defined in Studio as cutting-plane or free-form constraints. In other words, when you define a constraint, particles will be limited to the allowed area and will not cross into the disallowed region. - - - - -## Defining Cutting-Plane Constraints - -Follow the steps below to define cutting planes on an existing project: - -1. Make sure you are on the Data tab. -2. Click the Constraints drop-down menu. -![Plane 1](../img/studio/plane1.png){: width="300" } -3. ctrl+click 3 points on a shape surface to define a plane. -![Plane 2](../img/studio/plane2.png){: width="300" } -![Plane 3](../img/studio/plane3.png){: width="300" } - 1. Slide plane along the normal with shift+click. - ![Plane 4](../img/studio/plane4.png){: width="300" } - 2. Right click plane point to flip, delete or **copy plane to other shapes**. - ![Plane 5](../img/studio/plane5.png){: width="300" } -4. Now the newly defined cutting-plane constraint is active for the desired domain on the desired shape. This will show on the constraints panel. Now particles will not spread to the grayed out area. -![Plane 6](../img/studio/plane6.png){: width="300" } - -## Defining Free-Form Constraints - -Follow the steps below to define free-form constraints on an existing project: - -1. Make sure you are on the Data tab. -2. Click the Constraints drop-down menu. -![Plane 1](../img/studio/plane1.png){: width="300" } -3. Click the "Painting Enabled" toggle to checked. -![FFC 1](../img/studio/ffc1.png) - 1. Select brush size using slider if different from default. - ![FFC 2](../img/studio/ffc2.png){: width="300" } - 2. Select whether to paint included or excluded area. - ![FFC 3](../img/studio/ffc3.png){: width="300" } -4. Paint on the shape you would like to define the free-form constraint on. -![FFC 4](../img/studio/ffc4.png){: width="300" } -5. Now the newly-defined free form constraint is active for the desired domain on the desired shape. This will show on the constraints panel. Now particles will not spread to the grayed out area. -![FFC 5](../img/studio/ffc5.png){: width="300" } - -## Removing a Constraint - -To remove a constraint: - -1. Make sure you are on the Data tab with the constraints drop-down menu open. -2. The planes and free-form constraints previously defined will be listed. For cutting planes, you can also right click a plane point for the same effect. -![Delete 1](../img/studio/delete1.png){: width="300" } -3. To delete, select the one to delete and click delete. -![Delete 2](../img/studio/delete2.png){: width="300" } diff --git a/docs/use-cases/constraint-based/femur-cutting-planes-studio.md b/docs/use-cases/constraint-based/femur-cutting-planes-studio.md index c9bc1a0138a..d57c34bfb1b 100644 --- a/docs/use-cases/constraint-based/femur-cutting-planes-studio.md +++ b/docs/use-cases/constraint-based/femur-cutting-planes-studio.md @@ -12,7 +12,7 @@ Follow these instructions to start a new project and define constraints on your 1. Open ShapeWorks Studio and click "Start New Project" from the Splash Screen. If you just want to explore and not follow, you can just load Shapeworks/Examples/Studio/FemurConstraints/FemurConstraints.xlsx. 2. Drag-and-drop or import the femurs in Shapeworks/Examples/Studio/FemurConstraints. -3. Follow [the instructions for using constraints](../../studio/using-constraints.md) to define constraints. Here we define a cutting plane and a free-form constraint to each of four femurs. +3. Follow [the instructions for using constraints](../../studio/studio-data.md#using-constraints-in-studio) to define constraints. Here we define a cutting plane and a free-form constraint to each of four femurs. ## Grooming Steps diff --git a/docs/workflow/groom.md b/docs/workflow/groom.md index bc343e6c742..cf83aa91c76 100644 --- a/docs/workflow/groom.md +++ b/docs/workflow/groom.md @@ -315,7 +315,7 @@ In this step, we ingest the two original shapes and the output consists of three 5. Return three new shapes Lr, M and Rr ```python - extracted_l,extracted_r,extracted_s = + extracted_l,extracted_r,extracted_s = sw.MeshUtils.sharedBoundaryExtractor(mesh_l,mesh_r,tol) ``` #### Input shapes with shared surface @@ -324,8 +324,14 @@ In this step, we ingest the two original shapes and the output consists of three #### Output extracted surfaces ![Shared Boundary Output](../img/workflow/peanut_shared_output.png) +#### Multiple Shared Boundaries + +Projects with more than two domains can define multiple shared boundaries. Each shared boundary is specified as a pair of domains with a distance tolerance. For each pair, the extraction produces a shared surface domain (`shared_surface__`) and a shared boundary contour domain (`shared_boundary__`). + +Multiple shared boundaries can be configured in the Studio Groom module or in the project file directly. + ### Extract Contour -The boundary loop of the shared surface M obtained using the `sharedBoundaryExtractor` is computed. +The boundary loop of the shared surface M obtained using the `sharedBoundaryExtractor` is computed. ```python output_contour = sw.MeshUtils.boundaryLoopExtractor(extracted_shared_meshes) ``` diff --git a/docs/workflow/optimize.md b/docs/workflow/optimize.md index 440f6c2d388..f123ab7415f 100644 --- a/docs/workflow/optimize.md +++ b/docs/workflow/optimize.md @@ -152,10 +152,23 @@ To assess the quality of an optimized shape model, consider the following: ## Correspondences on New Samples -ShapeWorks supports an optimization mode, namely *fixed domains*, to place (i.e., optimize) correspondences on new shapes using a pre-existing shape model. In the fixed domains mode, particles on selected shapes that construct the pre-existing shape model are fixed, and particles on new shapes are optimized to represent them in the context of this shape model. See [Fixed Domains for Ellipsoid: Correspondences on New Shape](../use-cases/multistep/fixed-domain-ellipsoid.md) for an example. +ShapeWorks supports an optimization mode, namely *fixed domains*, to place (i.e., optimize) correspondences on new shapes using a pre-existing shape model. In the fixed domains mode, particles on selected shapes that construct the pre-existing shape model are fixed, and particles on new shapes are optimized to represent them in the context of this shape model. See [Fixed Domains for Ellipsoid: Correspondences on New Shape](../use-cases/multistep/fixed-domain-ellipsoid.md) for an example. -To enable the fixed domains mode, the XML should have the below additional tags. For this mode, you can use `"use_shape_statistics_after": 0` to enable shape statistics in all the steps as the pre-existing shape model already has enough particles optimized to reflect the covariance structure in the shape space. +To enable fixed domains in a project file, set the following parameters: -* ``: A list of *local.particles* files to be fixed, i.e., the pre-existing shape model. The new (to be optimized) samples/domains should be initialized with the mean particles. -* ``: A list of domain ids (starting from 0) of the domains that are fixed (i.e., not optimized). +* `use_fixed_subjects`: Set to `1` to enable fixed domains mode. +* `fixed_subjects_column`: The column name in the project spreadsheet that marks which shapes are fixed (e.g., `"fixed"`). +* `fixed_subjects_choice`: The value in that column that identifies fixed shapes (e.g., `"yes"`). + +For this mode, you can use `"use_shape_statistics_after": 0` to enable shape statistics in all the steps as the pre-existing shape model already has enough particles optimized to reflect the covariance structure in the shape space. + +### PCA Projection Correspondence + +By default, the correspondence term in fixed domain optimization minimizes ensemble entropy, which can pull new shapes toward the population mean. The `use_pca_projection` parameter offers an alternative: particles are projected into the PCA space of the fixed shapes, and only the **out-of-model residual** (the component not explained by any PCA mode) receives a gradient. Variation along PCA modes is left unconstrained, allowing new shapes to retain their natural deviation from the mean. + +To enable, add to the optimize parameters: + +```json +"use_pca_projection": true +``` diff --git a/install_shapeworks.bat b/install_shapeworks.bat index b8efaf2593f..feccc878613 100644 --- a/install_shapeworks.bat +++ b/install_shapeworks.bat @@ -11,7 +11,7 @@ call conda config --add channels anaconda call conda config --add channels conda-forge REM install shapeworks deps -call conda create --yes --name %CONDAENV% python=3.12 pip=24.3.1 openssl==0.3.30 || goto :error +call conda create --yes --name %CONDAENV% python=3.12.3 pip=24.3.1 openblas=0.3.30 || goto :error call conda activate %CONDAENV% REM reactivate shapeworks environment diff --git a/install_shapeworks.sh b/install_shapeworks.sh index cdb64bfcb07..6cdbac9a3a3 100644 --- a/install_shapeworks.sh +++ b/install_shapeworks.sh @@ -87,7 +87,7 @@ function install_conda() { conda config --add channels anaconda conda config --add channels conda-forge - CONDA_PACKAGES=(python=3.12 \ + CONDA_PACKAGES=(python=3.12.3 \ openblas=0.3.30 \ pip=24.3.1 ) diff --git a/mkdocs.yml b/mkdocs.yml index 31024b210d2..5d9d85c9707 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,10 +29,10 @@ nav: - 'How to Optimize Your Shape Model?': 'workflow/optimize.md' - 'Optimization Parameters': 'workflow/parameters.md' - 'How to Analyze Your Shape Model?' : 'workflow/analyze.md' -- What is New?: - - 'New in ShapeWorks Studio': 'new/new-studio.md' - - 'ShapeWorks Takes ~85% Less Memory': 'new/openvdb.md' - - 'ShapeWorks Directly on Meshes': 'new/sw-meshes.md' +- Feature Highlights: + - 'Studio Features': 'new/new-studio.md' + - 'Memory Efficiency with OpenVDB': 'new/openvdb.md' + - 'Mesh Support': 'new/sw-meshes.md' - 'ShapeWorks Command': 'new/shapeworks-command.md' - 'Shape Model Evaluation': 'new/ssm-eval.md' - 'ShapeWorks in Python': 'new/shapeworks-python.md'