This repository is released with this paper.
In case you would like to investigate the repo at state of publication, please check here.

The main purpose of this repository is to enable warping spatial annotations between correlated volume datasets of the same specimen that have been acquired with different imaging modalities.

A first purpose of this repository is enabling everyone to explore and reproduce annotations reported in the publication. This application is addressed by including the parameters of the correlative experiments described there.

A second purpose of this repository is to allow interested individuals to use, adapt or extend this solution to their needs/datasets/formats. This application is addressed by providing the codebase and instructions for installation and usage.

The transformations were fitted in bigwarp and executed using the code in this repository.

If you already have the repository on a given computer, check whether you got the latest version:

cd <path_to_this_repo>
git pull
git submodule update --recursive

Otherwise clone the repository:

git clone git@github.com:FrancisCrickInstitute/warpAnnotations.git --recursive

Note: On a given HPC cluster with the module command you might be able to just load these dependencies:

module load Java/1.8.0_202
module load Maven/3.6.0

You can otherwise install Java and Maven using the following resources:

• Install Java 1.8 from e.g. here or here

If opting for jdk, this would do the job (more info here):

brew tap homebrew/cask-versions
brew install --cask temurin8

And set JAVA_HOME path to its installed location.

# list all java installations
/usr/libexec/java_home -V
# obtain the path to the temurin installation
/usr/libexec/java_home -v 1.8.0_322
# update JAVA_PATH with the output of the previous command, such as
export JAVA_HOME="/Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home"

This JAVA_HOME path can be stated permanently to all your zsh sessions by adding that last command into your ~/.zshrc file.

• Download Maven and follow the installation instructions

Go to the bigwarp folder in your repo, e.g.: cd warping/bigwarp and compile it:

mvn compile

Create list of the dependencies of bigwarp in a file using this command:

mvn dependency:build-classpath | grep 'Dependencies classpath' -A 1 | tail -n 1 | tr ':' '\n' > ../javaclasspath.txt

The command will automatically replace all : separators with a newline \n character for Matlab compatibility.

Add the full path to the warping as well as the warping/bigwarp/target/classes subfolders at the top of that same javaclasspath.txt file. The former contains a small wrapper script to use the bigwarp functionality from Matlab and the latter contains the classes generated using mvn compile in the bigwarp directory.

Move the file javaclasspath.txt either to the top level of the repo under matlab-pipeline/ (and start Matlab from there during usage) or to your Matlab's prefdir to make the functionality available in Matlab permanently. Note that if using the second approach you will also have to manually run startup.m from this repo every time at the beginning of your MATLAB session.

Read more about adding to your static Java path.

The scale is specified in nm for each dimension.

The parameters specify the following properties:

• The source_ prefix refers to the dataset which will be transformed while the target_ prefix refers to the dataset after transformation.
• The mag_x, mag_y and mag_z parameters refer to the magnification of the dataset which was used, magnification refers to levels in the webknossos resolution pyramid
• The offset_x, offset_y and offset_z parameters indicate the offset in voxel if only part of the dataset was used to generate the landmarks
• The size_x, size_y and size_z parmaters indicate the size of the bounding box in voxel used to fit the landmarks
• The flip_x, flip_y, flip_z parameters indicate whether a version of the dataset in which a certain dimension was inverted was used
• The landmark parameter specifies a csv file with landmarks exported from bigwarp to be placed in the warping/data/landmarks folder
• The weight parameter is used if a chain of transformations is to be traversed to decide which path to take by default (the one with lowest weight)

This should then warp the skeleton to the other dataset and back to the original dataset (should be identical to the original one) as a sanity test. If you have specified multiple transformations you can try running multiple transformations at once as well using the warps function. Now you should be all set to transform skeletons between different webKnossos datasets as you please!

The following correlative multimodal annotations, reported in this paper, are available to explore:

The following correlative experiments are available to explore (links to the datasets here):

If you have any questions please contact us: Manuel Berning or Carles Bosch