Merge pull request #2527 from SCIInstitute/amorris/6.7-docs

Update docs for 6.7 release

Author: akenmorris

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

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 <project_file> [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 <file>` | Path to project file (alternative to positional argument) |
+| `--all` | Run all four steps: prep, augment, train, test |
+| `--prep <step>` | 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 <n>` | Number of PyTorch data loader workers (default: 0) |
+| `--aug_processes <n>` | 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`.

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 <Profiling.h>
+
+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");
+```

docs/img/studio/studio_dwd.png

@@ -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:  
 

docs/img/studio/studio_export_menu.png

@@ -1,25 +1,25 @@
-# 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" }
 
 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.
 
 <p><video src="https://sci.utah.edu/~shapeworks/doc-resources/mp4s/studio_alignments.mp4" autoplay muted loop controls style="width:100%"></p>
 
 See [Multiple Domain Alignments](../studio/multiple-domains.md#multiple-domain-alignments) for more information.
 
 ## 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.
 
 <p><video src="https://sci.utah.edu/~shapeworks/doc-resources/mp4s/studio_feature_scale.mp4" autoplay muted loop controls style="width:100%"></p>
 
@@ -82,27 +82,25 @@ 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)
 
 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" }
 
 See [Groom Module](../studio/getting-started-with-studio.md#groom-module) for more information.
 
 ## 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)