This release brings many changes including a unified graphical interface. We also cleaned up the command-line interface (CLI) to make it slightly simpler and more flexible. Please note that several options have changed, which may require updating custom scripts. The sample commands script (`bin/sample_cmds.sh`) has been updated to illustrate this usage.
Summary of CLI usage changes:
| Old | New | Purpose |
| --- | --- | --- |
| `python -m magmap.xx.yy` | `run_cli.py` | All command-line based entry points can be accessed through the CLI using this script |
| Use atlas profile for registration | No longer needed | Atlases should be fully imported before image registration, and the atlas's profile should no longer be typically given when registering an image |
| `--stats` | `--df` | Run data-frame (eg CSV file) tasks |
| `--roc` | `--grid_search <name1>[,name2]` | Its main task is to perform Grid Search based hyperparameter tuning; specify profile names or YAML files |
| `--rescale` | `--transform rescale=x` | Grouped with other transformation tasks |
| `--microscope <name1>[_name2]` | `--roi_profile <name1>[,name2]` | Specifies profiles to process by regions of interest; delimit by `,` to allow underscores especially in file paths |
| `--reg_profile <name1>[_name2]` | `--atlas_profile <name1>[,name2]` | Specifies profiles for atlases; delimit by `,` to allow underscores especially in file paths |
| `--saveroi` | `--save_subimg` | Consistency with "sub-images" as parts of images that can contain ROIs |
| `--chunk_size` | None | Obsolete |
| `finer` atlas profile | None | Its settings are now default |
| `--res` | `--set_meta resolutions=x,y,z` | Grouped custom metadata settings into `--set_meta` |
| `--mag` | `--set_meta magnification=x.y` | Grouped custom metadata settings into `--set_meta` |
| `--zoom` | `--set_meta zoom=x,y,z` | Grouped custom metadata settings into `--set_meta` |
| `--no_show` | `--show 0` | Show with `1` |
| `--no_scale_bar` | `--plot_labels scale_bar=1` | Grouped with other plot labels controls |
| `--padding_2d` | `--plot_labels margin=x,y,z` | Grouped with other plot labels controls, adding `margin` as space outside the ROI |
| `--border` | `--plot_labels padding=x,y,z` | Duplicated by the `padding` argument |
Changes
Installation
- New Windows install script
- The install scripts are now the recommended installation pathway
- Install scripts perform silent Miniconda installs after prompting
- Fixed the URL for Miniconda download
- Fixed the run script to include command-line arguments
GUI
- All new integrated graphical interface with unified ROI Editor, Atlas Editor, and 3D viewer in separate tabs alongside the controls panel
- ROI Editor
- Overview plot zooming scales to the size of the ROI
- Orange border highlights the ROI z-plane corresponding to the overview plots
- Shows similar pixel information as in the Atlas Editor
- Layout now respects labels
- Title now specifies axes
- Title and empty ROI plots compatible with dark theme
- Halve the size of truth blobs in verification plots to avoid obscuring the underlying image
- Easier to flag detections in the ROI Editor
- GUI image loading
- Load sub-images through the GUI
- Fixed loading the GUI without an image
- Fixed loading images through the GUI
- Fixed image coordinate limits after loading an image
- Region selection
- Option to select multiple regions, separating IDs by `,`
- Selecting a region ID shows its basic measurements
- Fixed potential for label boundaries to exceed image boundaries
- Isotropic rescaling is turned on by default for 3D visualizations and incorporates image resolution
- `NaN` values can be used for invisible pixels, which reduces opacification when highlighting an atlas label in the ROI Editor
- 3D surface rendering is now default
- Unified save button for all viewers
- Auto-select a channel when restoring an ROI based on saved blobs' channel
- Fixed hang when opening the Atlas Editor for large images (downsamples images if necessary)
- Fixed error when showing an image with the z-offset set to the maximum value
- Fixed clearing picked colors during atlas painting
- Fixed the aspect ratio for images rotated 90 degrees
- Fixed display of RGB values for labels
- Fixed over darking some text boxes when hovering
- Fixed blob alignment in 3D surface rendering
CLI
- The CLI now serves as a unified entry point to the Command Line Interface, incuding `register`, `plot_2d`, and other tasks,
- The CLI can be accessed through the `run_cli.py` script, which benefits from the environment setup in `run.py` without loading a window
- `--proc preprocess` option to preprocess whole images by tasks specified in a `preprocess` ROI profile setting
- Many more sample commands for common tasks
- Better support for using the sample commands script without modification
- Help information added for command-line arguments
- Command-line arguments are checked for valid options when available
- Task to export image planes to separate files (`--proc export_planes`)
- Fixed sample commands for sub-images
- Fixed sample commands path setup for older versions of Bash (< 4.3)
Atlas refinement
- Resize images using the `--size` argument as an alternative to a profile setting
- Atlas operations expecting symmetry have been generalized across any axis
- Apply adaptive histogram equalization (access as a preprocessing task)
- Records total volumes of atlas and labels during atlas import
- Fixed rotation with resizing for non-z axes
- Fixed storing image plane boundaries for label contour interpolation
Atlas registration
- The atlas is assumed to be pre-imported, which avoids redundant atlas import tasks
- Support for more pre-registration atlas pre-processing tasks, such as 3D rotation, inversion, cropping, and rescaling
- Saves a truncated labels and pre-curated images only if the corresponding options are set
- Option to rescale units (eg mm to microns)
- Settings are customizable for each registration transformation task (eg translation, affine) rather than globally
- Defaults to increased b-spline iterations
- Fixed display of images through SimpleITK after registration
Volumetric image processing
- Grid Search profiles
- Configurable as YAML files
- Fixed Grid Searches without sub-image parameters
- Provides basic detection accuracy stats when saving blobs
- Option for whole-image contrast limited adaptive histogram equalization (using scikit-image)
- Fixed retrieving saved ROIs from the database
I/O
- Import from a directory of images
- Option to convert RGB images to grayscale when importing images from a directory
- Import multi-channel images
- Fixed importing large images
- Option to specify output paths when importing a image directory or multi-page TIFF
- Can load multi-page TIFF files without channel indicator
- Defaults to saving figures as PNG
- Library functions for listing, downloading, and uploading files in AWS S3
- Library functions for de/compressing and testing files using ZSTD
- Allows loading the main image from a registered image path
- Avoids loading a sub-image when saving it to avoid a hang
- Sample YAML profiles for blob detection, registration
- `profiles` folder is checked automatically when loading YAML profiles
Python stats and plots
- Command-line options for configuring markers (`--plot_labels marker`) and annotation columns (`--plot_labels annot_col`)
R stats and plots
- Simple R script to load and run stats
Code base and docs
- Licensed under the [BSD-3 open source license](../../LICENSE.txt)
- Moved AWS cloud management to a [separate document](../cloud_aws.md)
Dependency Updates
Python Dependency Changes
- Javabridge custom binary updated for import fix on MacOS
- Removed redundant PyQt5 installation during Conda installs
- Workaround for VTK 9 incompatibility with currently Mayavi dependency