Continuous Registration Banner

Participation

You need to do three things to participate in the challenge:

1. Build SuperElastix (full documentation here)

  1. Fork SuperElastix to your own GitHub account (optional but makes it easier to submit a PR down the line)

  2. Clone SuperElastix:

        $ git clone https://github.com/SuperElastix/SuperElastix

  3. Checkout your own branch for development (optional):

        cd SuperElastix && git checkout -b my-branch

  4. Build SuperElastix in a separate directory:

        cd .. && mkdir -p build/SuperElastix && cd build/SuperElastix && cmake ../SuperElastix/SuperBuild && make -j4

  5. Run tests (optional):

        cd SuperElastix-build && ctest -j4

2. Create your own SuperElastix component and/or parameter file (full documentation here)

  1. Copy the Modules/ExampleComponent directory to Modules/MyComponent (replace "MyComponent" with your components name here in the subsequent steps).
  2. Replace "ExampleComponent" with your own component name, e.g. "MyComponent", in the filenames in ModuleExampleComponent.cmake, and in include/, src/, and test/ directories. Rename the class in the sourcefiles as well.
  3. Compile the code, and run tests (if you made any) by running "ctest -R MyComponent" in the build directory. If you have changed all the names to MyComponent, you will see the test name and status PASSED in your terminal (remember to also rename the test in the test source directory).
  4. Create your parameter file. You can copy e.g. ContinuousRegistration/TeamElastix/ElastixAffineTransform.json and start from there. You need to keep the "FixedImage", "FixedMask", "MovingImage", "MovingMask" (inputs), the "DisplacementField" (output) and the connections between the components. Edit the "RegistrationMethod" component to use your own class. You should also set the "Dataset" list to contain the names of the data sets you whish your method to be tested on (ElastixAffineTransform.json is tested on all data sets in the challenge).
  5. Your method should output a deformation a DisplacementField with the same world coordinatae system as the fixed image. The DisplacementField should map from the fixed image to the moving image, such that we can loop over all voxel positions in the displacement field, add the displacement, and look up the pixel value in the moving image. This will transform the moving image into the fixed image domain. We use the deformation field to warp the ground truth for evaluation.

3. Create a Pull Request (PR) (full documentation here)

  1. Request an invite to the join the SuperElastix organization on GitHub on the challenge's Googe Groups mailing list. Remember to include your GitHub username.
  2. Fork the SuperElastix repository to your own account and push your own SuperElastix repository (full GitHub documentation).
  3. Submit a PR to the SuperElastix repository at https:/github.com/SuperElastix/SuperElastix  (full GitHub documentation here).
  4. Our Continuous Integration (CI) Jenkins server will build your code. A successful build is required for merging the PR. If the build fails, you can check the CDash page to view compilation errors (you should always be able to build locally before pushing, since the feedback loop here much quicker). 

Running registrations locally

Testing registrations locally will is helpful when designing and tune your algorithm. You can use the framework that we use to run registration on our cluster to run registrations on your own computer as well.

In the ContinuousRegistration/Source directory in the SuperElastix repository you will find a set of Python scripts that you can use to run the registration. register.py generates shell and/or batch scripts that you can invoke to run the registration (we just qsub these scripts to our cluster). evaluate.py can be used to evaluate the results after registration has been run. These scripts takes the following command line arguments

  • --superelastix: Full path to SuperElastix executable (e.g. in build/SuperElastix/SuperElastix-build/bin/SuperElastix.
  • --submissions-directory: Full path to the ContinuousRegistration/Submissions directory.
  • --output-directory: Full path to directory where registration results and evaluation results are saved.

In addition, you should provide directories to the data sets you wish to run the registrations on. These arguments are:

  • --cumc12-input-directory
  • --empire-input-directory
  • --isbr18-input-directory
  • --lpba40-input-directory
  • --mgh10-input-directory
  • --spread-input-directory
  • --popi-input-directory
  • --dirlab-input-directory
  • --popi-masks-directory (masks coming soon, can be omitted for now)

These following commands to register and evaluate the ISBR18 data set:

  • cd SuperElastix (i.e., the SuperElastix source directory)
  • python -m ContinuousRegistration.Source.make_registration_scripts.py --superelastix /Users/kasper/Development/build/SuperElastix/SuperElastix-build/bin/SuperElastix --submissions-directory /Users/kasper/Development/SuperElastix/ContinuousRegistration/Submissions --output-directory /Users/kasper/Data/ContinuousRegistration --isbr18-input-directory /Users/kasper/Development/SuperBenchData/ISBR18 --max-number-of-registrations-per-dataset 4
  • cd /Users/kasper/Data/ContinuousRegistration (i.e. output directory)
  • find . -type f -name "*.sh" | parallel -j 4
  • cd SuperElastix (i.e., the root SuperElastix source directory)
  • python -m ContinuousRegistration.Source.make_evaluation --superelastix /Users/kasper/Development/build/SuperElastix/SuperElastix-build/bin/SuperElastix --submissions-directory /Users/kasper/Development/SuperElastix/ContinuousRegistration/Submissions --output-directory /Users/kasper/Data/ContinuousRegistration --isbr18-input-directory /Users/kasper/Development/SuperBenchData/ISBR18 --max-number-of-registrations-per-dataset 4
  • (optional) python -m ContinuousRegistration.Source.make_leaderboard --superelastix /Users/kasper/Development/build/SuperElastix/SuperElastix-build/bin/SuperElastix --submissions-directory /Users/kasper/Development/SuperElastix/ContinuousRegistration/Submissions --output-directory /Users/kasper/Data/ContinuousRegistration --isbr18-input-directory /Users/kasper/Development/SuperBenchData/ISBR18 --max-number-of-registrations-per-dataset 4

You can supply the following arguments to make_evaluation.py to produce visualizations of the registration:

  • --make-images: Warp images and write to disk
  • --make-labels: Warp labels and write to disk
  • --make-image-checkerboards: Make checkerboard pattern with fixed and warped moving image
  • --make-label-checkerboards: Make checkerboard pattern with fixed and warped moving label

You can supply multiple data sets at the same time.   The expected file layout on disk is described on data page. If you download data sets from their original sources as listed on the data page, the data directory structure should match the expected layout. No need to mess around with files on your part.  

More resources

  1. SuperElastix documentation at superelastix.readthedocs.io.
  2. The SuperElastix paper.

For questions, feedback and other direct communication, use our slack channel (request invite here), open an issue on GitHub or post on the Google Group mailing list. Whatever you prefer.