This repository contains extensions, plugins, for the Imaris (Oxford Instruments) microscopy image analysis program. They either provide additional image analysis capabilities via the open source SimpleITK image analysis library, or are utilities that allow the user to easily modify meta-data associated with images stored in the Imaris file format (e.g. channel names, colors).
The extensions are designed so that they can be run either as independent programs or via the Imaris extension mechanism. When run as independent programs they can be used on any of the standard operating systems (Windows/OSX/Linux).
Software development notes:
Using zip file: Download the zip file for a specific
release or the latest
code’s zip file. Replace older versions with the contents of the zip
file (don’t forget to keep the run_extensions.bat
,
run_extensions.sh
files which you previously modified for
your setup).
Using git: Initially, clone repository using git (with GitHub
account).
git clone https://github.com/niaid/imaris_extensions.git
Update to latest code: git pull
If updating, you will want to remove or rename the existing Python environment:
conda remove -n imaris --all
or
conda rename -n imaris old_imaris
Then, recreate the imaris
environment, step 2 in the setup instructions below.
If you find these extensions useful in your research, support our efforts by citing it as:
Z. Yaniv, B. Lowekamp, “SimpleITK Imaris Extensions”, doi: 10.5281/zenodo.7854019.
⚠ WARNINGS
Avoid converting files into imaris format using a network or external drive, this has the potential to produce corrupt files that are hard to identify as such (unless you enjoy hours of debugging). This issue is not specific to the work found here. For more details see the XTRegisterSameChannel documentation.
Corrupt files will cause the extensions to fail with an error message “…OSError: Can’t read data (inflate() failed)”. In some cases imaris is able to read such files while the extensions fail to do so. A solution, that often works, is to read the file into imaris and then “Save as” to a new file which can then be read by the extensions.
Out of memory errors will cause the extensions to
fail with an error message along the lines of “…Failed to allocate
memory for image.”. The minimal RAM size required to run an
extension depends on the image sizes and the specific extension in use.
For common image sizes, 16GB of RAM is often
sufficient, 64GB or more is desirable. If memory size
is not sufficient, consider increasing the size of the machine’s virtual memory.
Experience has shown us that some extensions,
e.g. XTChannelArithmetic
, do work on systems with only
8GB of RAM when configured appropriately (using a
memory efficient slice-by-slice processing at the cost of longer
runtimes).
source path_to_your_anaconda3/bin/activate base
cd path_to_your_extensions_directory
conda env create -f environment.yml
Configure Imaris to point to your Python executable and to the
directory containing the extensions (see Imaris manual).
Note: this is an optional step, if you don’t have the
Imaris software on the specific machine you can still run the
extensions.
Edit one of these files, set the path to your Python
executable:
Windows: run_extensions.bat
OSX/Linux: run_extensions.sh
Run the relevant script:
Windows: double click the
run_extensions.bat
.
OSX/Linux: from a terminal, make the script
executable chmod +x run_extensions.sh
and run it
./run_extensions.sh
.
Bonus: On OSX, you can configure things so that double clicking the script in Finder will run it. In Finder,