Skip to content

Usage examples

Jump to bottom
John Bogovic edited this page Feb 27, 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 - utilities for converting between transform formats.
  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.
  • -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: input parser [options]
  Options:
    -d, --directory
       Directory containing skeletons
    --exclude
       Exclusion pattern: Files matching the given regular expression will be
       ignored. Only relevant when pass a directory
    -h, --help
       Print this help message
       Default: false
    --include
       Matching pattern: Files not matching the given regular expression will be
       ignored.  Only relevant when passing a directory
    -o, --output
       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
       Input skeletons. Can pass multiple skeletons
    --suffix
       Suffix applied to output files when passing a directory.
       Default: _transformed
    -t, --transform
       Transforms
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>

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

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