Skip to content

Usage examples

Jump to bottom
John Bogovic edited this page Mar 22, 2019 · 30 revisions

Contents

  1. Prerequisites - installation and sample data
  2. Transforming images - code for rendering and transforming images
  3. Transforming neuron skeletons - code for transforming neurons in swc format
  4. Converting transforms
  5. CMTK example - converting a h5 transform to CMTK-compatible format and applying it with CMTK's reformatx.
  6. Processing swc's - process / edit swc neuron files

Prerequisites

  • Install jgo
  • Clone and install this repository:
git clone https://github.com/saalfeldlab/template-building.git
cd template-building
git checkout v0.1.0
mvn clean compile install

Sample data

Some of these examples use sample data that can be downloaded from figshare.

Image data

Include are:

  • A downsampled version of the JRC 2018 female template.
  • A downsampled version of the FCWB template.

Neuron

The neuron skeleton included here comes from the FlyCircuit database and accessed through Greg Jefferis' flycircuit R package

Transforming images

We recommend using the transformImage shell script for transforming images.

Usage: transformImage [-v] [--interpolation=<interpolation>] [-j=<nThreads>]
                    [-s=<outputSize>] -i=<inputFiles> [-i=<inputFiles>]...
                    -o=<outputFiles> [-o=<outputFiles>]...
                    [-r=<outputResolution>[,<outputResolution>...]]...
                    [-t=<transformFiles>]...
      --interpolation=<interpolation>
                             Interpolation {LINEAR, NEAREST, LANCZOS}
  -i, --input=<inputFiles>   Image file to transform
  -j, --nThreads=<nThreads>  Number of rendering threads (default=1)
  -o, --output=<outputFiles> Output file for transformed image
  -r, --output-resolution=<outputResolution>[,<outputResolution>...]
                             The resolution at which to write the output
  -s, --outputImageSize=<outputSize>
                             Size of image output in pixels
  -t, --transform=<transformFiles>
                             Transformation file.
  -v, --version              Prints version information and exits.

Examples

FCWB template to JRC2018F

Uses this sample data.

transformImage -i FCWB_small.nrrd \
    -o fcwb-to-jrc18f.nrrd \
    -f JRC2018_FEMALE_small.nrrd \
    -t JRC2018F_FCWB_small.h5 \
    -j 4

Summary of arguments:

  • -i FCWB_small.nrrd
    • the input image we to transform is the FCWB template
  • -o fcwb-to-jrc18f.nrrd
    • give the name of the output image
  • -f JRC2018_FEMALE_small.nrrd
    • the field-of-view and image resolutions of the output image should be that of the JRC2018F template
  • -t JRC2018F_FCWB_small.h5
    • use the transform mapping JRC2018F to FCWB see here for details on this nomenclature and directions of transforms.
  • -j 4
    • Use four threads for parallel rendering

JRC2018F template to FCWB

Uses this sample data.

transformImage -i JRC2018_FEMALE_small.nrrd \
    -o jrc18f-to-fcwb.nrrd \                                                                                             
    -f FCWB_small.nrrd \
    -t JRC2018F_FCWB_small.h5??i \
    -j 4

Summary of arguments:

  • -i JRC2018_FEMALE_small.nrrd
    • the input image we to transform is the FCWB template
  • -o jrc18f-to-fcwb.nrrd
    • give the name of the output image
  • -f FCWB_small.nrrd
    • the field-of-view and image resolutions of the output image should be that of the JRC2018F template
  • -t JRC2018F_FCWB_small.h5??i
    • use the inverse transform mapping JRC2018F to FCWB see here for details on this nomenclature and directions of transforms.
    • See this page for details on how inverses of transforms are handled.
  • -j 4
    • Use four threads for parallel rendering

Transforming skeletons

These examples show how to transform neuronal skeletons stored as swc files. We recommend using the transformSwc shell script or the transform_swc fiji script.

Shell script options

You can see a summary of the options by running

$ transformSwc --help
Usage: <main class> [-hv] [--dry-run] [--exclude=<excludeMatcher>]
                    [--include=<includeMatcher>] [--suffix=<suffix>]
                    [-d=<skeletonDirectory>] [-o=<outputSkeletonPaths>]...
                    [-s=<skeletonPaths>]... [-t=<transforms>]...
      --dry-run           Prints files to work on, but does nothing.
      --exclude=<excludeMatcher>
                          Exclusion pattern: Files matching the given regular
                            expression will be ignored. Only relevant when pass a
                            directory
      --include=<includeMatcher>
                          Matching pattern: Files not matching the given regular
                            expression will be ignored.  Only relevant when passing
                            a directory
      --suffix=<suffix>   Suffix applied to output files when passing a directory.
  -d, --directory=<skeletonDirectory>
                          Directory containing skeletons
  -h, --help              Print this help message
  -o, --output=<outputSkeletonPaths>
                          Output skeleton file names. Must have one output for every
                            input skeleton, and pass outputfile paths in the same
                            order as the input sketons.
  -s, --skeleton=<skeletonPaths>
                          Input skeletons. Can pass multiple skeletons
  -t, --transform=<transforms>
                          List of transforms.  Every transform that is passed will
                            be applied to the skeletons in the order they are
                            passed. -t <transform file path> applies the inverse of
                            the given transform if possible.
  -v, --version           Prints version information and exits.
Basic usage

Transform an skeleton and write it to an output file

transformSwc -s <swc skeleton file> -o <output file> -t <transform file>

Transform multiple skeletons with the same transforms:

transformSwc \
   -s <swc skeleton file 1> -o <output file 1> \ 
   -s <swc skeleton file 2> -o <output file 2> \
   -t <transform file>

Transform a skeleton with a sequence of transforms (some inverted). In this example the inverse of the third transform is applied:

transformSwc \
   -s <swc skeleton file> -o <output file> \ 
   -t <transform file 1> -t <transform file 2> -t inverse <transform file 3>
Batch transforming files in a directory

transformSwc can operate on all files in a directory

transformSwc -d <directory> -t <transform>

applies the transform to all swc files in directory. Use of the -d flag overrides any skeletons passed with -s flags. In this case, the suffix _transformed is appended to any processed files. The suffix can be changed using the ``--suffix` flag:

transformSwc -d <directory> -t <transform> --suffix _hippo

If you want to process some, not all, of the files in a directory, the --include`` and --exclude` flags let you pass a regular expression for files to include and exclude, respectively. Note inclusions are are processed before exclusions.

Example, to process files in a directory starting with an "a":

transformSwc -d <directory> -t <transform> --include '^a.*'

Example, to exclude files with a number anywhere in the file name:

transformSwc -d <directory> -t <transform> --exclude '.*[0-9].*'

Example - transform neuron skeleton from FCWB to JRC2018F

Uses this sample data.

transformNeuron \
    -s GadMARCM-F000122_seg001_03.swc \
    -o GadMARCM_xfm-to-jrc18f.swc \
    -t JRC2018F_FCWB_small.h5??i

Summary of arguments:

  • s GadMARCM-F000122_seg001_03.swc
    • the input skeleton to transform
  • -o GadMARCM_xfm-to-jrc18f.swc
    • the name of the output skeleton
  • -t JRC2018F_FCWB_small.h5??i
    • use the inverse of the JRC2018F_FCWB because the inverse maps points from FCWB to JRC2018F see here for details on this nomenclature and directions of transformations.

Results

FCWB space JRC2018F space

Converting transforms

Example - convert an h5 transform to cmtk's format

Uses this sample data.

convertAffine JRC2018F_FCWB_small.h5 JRC2018_FEMALE_small.xform

# convert forward deformation field
convertDfield JRC2018F_FCWB_small.h5 JRC2018F_FCWB_small_fwd.nrrd

# convert inverse deformation field
convertDfield JRC2018F_FCWB_small.h5??i JRC2018F_FCWB_small_inv.nrrd

# Use cmtk to apply transform to FCWB
reformatx --floating FCWB_small.nrrd \
    -o cmtk_fcwb-to-jrc18f.nrrd \
    JRC2018_FEMALE_small.nrrd \
    JRC2018F_FCWB_small_fwd.nrrd JRC2018_FEMALE_small.xform 

# Use cmtk to apply transform to JRC2018F
reformatx --floating JRC2018_FEMALE_small.nrrd \
    -o cmtk_jrc18f-to-fcwb.nrrd \
    FCWB_small.nrrd \
    -i JRC2018_FEMALE_small.xform JRC2018F_FCWB_small_inv.nrrd
  • convertAffine
    • xform is cmtk's extension for transformations

Converting arbitrary transform to a deformation field

It may sometimes be useful to concatenate transformations to a single file. Deformation fields, being the most general representation, is a natural choice. The transform2Dfield implements this.

Usage: <main class> [-f=<referenceImagePath>] -o=<outputFile> [-q=<nThreads>]
                    [-s=<outputSize>] [-r=<outputResolution>[,
                    <outputResolution>...]]... [-t=<transformFiles>]...
  -f, --reference=<referenceImagePath>
         A reference image specifying the output size and resolution.
  -o, --output=<outputFile>
         Output file for transformed image
  -q, --nThreads=<nThreads>
         Number of threads.
  -r, --output-resolution=<outputResolution>[,<outputResolution>...]
         The resolution at which to write the output. Overrides reference image.
  -s, --outputImageSize=<outputSize>
         Size / field of view of image output in pixels.  Comma separated, e.g.
           "200,250,300". Overrides reference image.
  -t, --transform=<transformFiles>
         Transformation file.

Example - iteratively compute the inverse of a deformation field

transform2Dfield
   -t <deformation field>?<inverse-options>?i
   -o <output file>

Read about details of iterative inverses here.

A demonstration can be found here using this sample data.

Processing swc files

Some common operations on swc neuron file are implemented by the script processNeuron:

Usage: <main class> [-h] [--set-radius=<radiusValue>] [-r=<radiusScaling>[,
                    <radiusScaling>...]] [-c=<coordinateScaling>[,
                    <coordinateScaling>...]]... [-o=<outputSkeletonPaths>]...
                    [-s=<skeletonPaths>]...
      --set-radius=<radiusValue>
                        Set radius. The radius at every point will be set to this
                          value. This takes precedence over radius scaling.
  -c=<coordinateScaling>[,<coordinateScaling>...]
                        Coordinate scaling
  -h, --help            Print this help message
  -o=<outputSkeletonPaths>
                        Output skeletons. You can
  -r=<radiusScaling>[,<radiusScaling>...]
                        Radius scaling
  -s=<skeletonPaths>    Input skeletons. You can provide multiple -s options

Examples

Scale spatial coordinates

Scale x, y, and z coordinates by factors of 2, 3, and 4, respectively.

processNeuron -s GadMARCM-F000122_seg001_03.swc \ 
  -o GadMARCM-F000122_seg001_03_scaledCoordinates.swc \
  -c 2,3,4

Scale radii

Scale radii by a factor of 10

processNeuron -s GadMARCM-F000122_seg001_03.swc \ 
  -o GadMARCM-F000122_seg001_03_scaledCoordinates.swc \
  -r 10

Set radius

Set the value of the radius to 1.0 everywhere

processNeuron -s GadMARCM-F000122_seg001_03.swc \ 
  -o GadMARCM-F000122_seg001_03_scaledCoordinates.swc \
  --set-radius 1.0
Clone this wiki locally