mia-3dnonrigidreg(1)

📦
version 2.4.7 · 4 versions
, in ubuntu resolute, ubuntu stonking

okay bestie, this is the manual page for mia-3dnonrigidreg(1) — general commands manual section, iykyk 💖. It's giving "non-linear registration of 3D images" and we're gonna go through every single detail, no cap. Let's go ✨.

✨ NAME ✨

mia-3dnonrigidreg — Non-linear registration of 3D images. That's it, that's the whole point: it registers two 3D images non-linearly. Periodt.

🌸 SYNOPSIS 🌸

mia-3dnonrigidreg -i <in-image> -r <ref-image> -o <out-image> [options]
<PLUGINS:3dimage/fullcost>

🦋 DESCRIPTION 🦋

So mia-3dnonrigidreg? This program implements the registration of two gray scale 3D images. That's the vibe. It's literally matching up two 3D grayscale images in a non-linear way. Slay.

💅 OPTIONS 💅

🎀 Help & Info 🎀

  • -V, --verbose=warning — verbosity of output, print messages of given level and higher priorities. Supported priorities starting at lowest level are:
    • trace — Function call trace
    • debug — Debug output
    • info — Low level messages
    • message — Normal messages
    • warning — Warnings
    • fail — Report test failures
    • error — Report errors
    • fatal — Report only fatal errors
  • --copyright — print copyright information
  • -h, --help — print this help
  • -?, --usage — print a short help
  • --version — print the version number and exit

🫶 IO 🫶

  • -i, --in-image=(input, required); io — test image. For supported file types see PLUGINS:3dimage/io
  • -r, --ref-image=(input, required); io — reference image. For supported file types see PLUGINS:3dimage/io
  • -o, --out-image=(output, required); io — registered output image. For supported file types see PLUGINS:3dimage/io
  • -t, --transformation=(output); io — output transformation. For supported file types see PLUGINS:3dtransform/io

😭 Processing 😭

  • --threads=-1 — Maxiumum number of threads to use for processing,This number should be lower or equal to the number of logical processor cores in the machine. (-1: automatic estimation).

👑 Registration 👑

  • -l, --levels=3 — multi-resolution levels
  • -O, --optimizer=gsl:opt=gd,step=0.1 — Optimizer used for minimization. For supported plugins see PLUGINS:minimizer/singlecost
  • -f, --transForm=spline:rate=10 — transformation type. For supported plugins see PLUGINS:3dimage/transform

🌈 PLUGINS: 1d/spacialkernel 🌈

cdiff

Central difference filter kernel, mirror boundary conditions are used.

(no parameters)

gauss

spacial Gauss filter kernel, supported parameters are:

  • w = 1; uint in [0, inf) — half filter width.

scharr

This plugin provides the 1D folding kernel for the Scharr gradient filter

(no parameters)

💜 PLUGINS: 1d/splinebc 💜

mirror

Spline interpolation boundary conditions that mirror on the boundary

(no parameters)

repeat

Spline interpolation boundary conditions that repeats the value at the boundary

(no parameters)

zero

Spline interpolation boundary conditions that assumes zero for values outside

(no parameters)

✨ PLUGINS: 1d/splinekernel ✨

bspline

B-spline kernel creation , supported parameters are:

  • d = 3; int in [0, 5] — Spline degree.

omoms

OMoms-spline kernel creation, supported parameters are:

  • d = 3; int in [3, 3] — Spline degree.

🍓 PLUGINS: 3dimage/combiner 🍓

absdiff

Image combiner 'absdiff'

(no parameters)

add

Image combiner 'add'

(no parameters)

div

Image combiner 'div'

(no parameters)

mul

Image combiner 'mul'

(no parameters)

sub

Image combiner 'sub'

(no parameters)

🧚 PLUGINS: 3dimage/cost 🧚

lncc

local normalized cross correlation with masking support., supported parameters are:

  • w = 5; uint in [1, 256] — half width of the window used for evaluating the localized cross correlation.

mi

Spline parzen based mutual information., supported parameters are:

  • cut = 0; float in [0, 40] — Percentage of pixels to cut at high and low intensities to remove outliers.
  • mbins = 64; uint in [1, 256] — Number of histogram bins used for the moving image.
  • mkernel = [bspline:d=3]; factory — Spline kernel for moving image parzen hinstogram. For supported plug-ins see PLUGINS:1d/splinekernel
  • rbins = 64; uint in [1, 256] — Number of histogram bins used for the reference image.
  • rkernel = [bspline:d=0]; factory — Spline kernel for reference image parzen hinstogram. For supported plug-ins see PLUGINS:1d/splinekernel

ncc

normalized cross correlation.

(no parameters)

ngf

This function evaluates the image similarity based on normalized gradient fields. Given normalized gradient fields $ _S$ of the src image and $ _R$ of the ref image various evaluators are implemented., supported parameters are:

  • eval = ds; dict — plugin subtype (sq, ds,dot,cross). Supported values are:
    • ds — square of scaled difference
    • dot — scalar product kernel
    • cross — cross product kernel

ssd

3D image cost: sum of squared differences, supported parameters are:

  • autothresh = 0; float in [0, 1000] — Use automatic masking of the moving image by only takeing intensity values into accound that are larger than the given threshold.
  • norm = 0; bool — Set whether the metric should be normalized by the number of image pixels.

ssd-automask

3D image cost: sum of squared differences, with automasking based on given thresholds, supported parameters are:

  • rthresh = 0; double — Threshold intensity value for reference image.
  • sthresh = 0; double — Threshold intensity value for source image.

🌸 PLUGINS: 3dimage/filter 🌸

bandpass

intensity bandpass filter, supported parameters are:

  • max = 3.40282e+38; float — maximum of the band.
  • min = 0; float — minimum of the band.

binarize

image binarize filter, supported parameters are:

  • max = 3.40282e+38; float — maximum of accepted range.
  • min = 0; float — minimum of accepted range.

close

morphological close, supported parameters are:

  • hint = black; string — a hint at the main image content (black|white).
  • shape = [sphere:r=2]; factory — structuring element. For supported plug-ins see PLUGINS:3dimage/shape

combiner

Combine two images with the given combiner operator. if 'reverse' is set to false, the first operator is the image passed through the filter pipeline, and the second image is loaded from the file given with the 'image' parameter the moment the filter is run., supported parameters are:

  • image =(input, required, io) — second image that is needed in the combiner. For supported file types see PLUGINS:3dimage/io
  • op =(required, factory) — Image combiner to be applied to the images. For supported plug-ins see PLUGINS:3dimage/combiner
  • reverse = 0; bool — reverse the order in which the images passed to the combiner.

convert

image pixel format conversion filter, supported parameters are:

  • a = 1; float — linear conversion parameter a.
  • b = 0; float — linear conversion parameter b.
  • map = opt; dict — conversion mapping. Supported values are:
    • copy — copy data when converting
    • linear — apply linear transformation x -> a*x+b
    • range — apply linear transformation that maps the input data type range to the output data type range
    • opt — apply a linear transformation that maps the real input range to the full output range
    • optstat — apply a linear transform that maps based on input mean and variation to the full output range
  • repn = ubyte; dict — output pixel type. Supported values are:
    • bit — binary data
    • sbyte — signed 8 bit
    • ubyte — unsigned 8 bit
    • sshort — signed 16 bit
    • ushort — unsigned 16 bit
    • sint — signed 32 bit
    • uint — unsigned 32 bit
    • slong — signed 64 bit
    • ulong — unsigned 64 bit
    • float — floating point 32 bit
    • double — floating point 64 bit
    • none — no pixel type defined

crop

Crop a region of an image, the region is always clamped to the original image size in the sense that the given range is kept., supported parameters are:

  • end = [[4294967295,4294967295,4294967295]]; streamable — end of cropping range, maximum = (-1,-1,-1).
  • start = [[0,0,0]]; streamable — begin of cropping range.

dilate

3d image stack dilate filter, supported parameters are:

  • hint = black; string — a hint at the main image content (black|white).
  • shape = [sphere:r=2]; factory — structuring element. For supported plug-ins see PLUGINS:3dimage/shape

distance

Evaluate the 3D distance transform of an image. If the image is a binary mask, then result of the distance transform in each point corresponds to the Euclidian distance to the mask. If the input image is of a scalar pixel value, then the this scalar is interpreted as heighfield and the per pixel value adds to the distance.

  • (no parameters) — nope, nothing, zero params, it just does its lil thing and that's that ✨

downscale 💖

Lowkey the glow-down of image filters: it shrinks your input image by picking a block size and using that as the downscale factor. But bestie, before it scales anything it runs a smoothing filter first, so the high-frequency data gets yeeted and you don't get aliasing artifacts. Skincare routine for pixels, fr.

  • b = [[1,1,1]] 3dbounds — the blocksize.
  • bx = 1 uint in [1, inf) — blocksize in the x direction.
  • by = 1 uint in [1, inf) — blocksize in the y direction.
  • bz = 1 uint in [1, inf) — blocksize in the z direction.
  • kernel = gauss factory — the smoothing filter kernel that gets applied, and the filter size is estimated based on the blocksize. For supported plug-ins see PLUGINS:1d/spacialkernel.

erode 🫶

A 3d image stack erode filter. Shrinky vibes but make it morphology.

  • hint = black string — a hint at the main image content (black|white).
  • shape = [sphere:r=2] factory — the structuring element. For supported plug-ins see PLUGINS:3dimage/shape.

gauss 🎀

Isotropic 3D gauss filter, the classic. Blurred but make it three-dimensional.

  • w = 1 int in [0, inf) — filter width parameter.

gradnorm 🌈

3D image to gradient norm filter. That's the whole job description, periodt.

  • (no parameters) — nothing to configure, it's giving effortless.

growmask 🦋

Okay so this one takes an input binary mask plus a reference gray scale image, and does region growing: it keeps adding neighborhood pixels of a pixel that's already in, but only if those neighbors have a lower intensity that's still above the given threshold. Very "invite the whole group chat" energy.

  • min = 1 float — lower threshold for mask growing.
  • ref (input, required, io) — reference image for mask region growing. For supported file types see PLUGINS:3dimage/io.
  • shape = 6n factory — the neighborhood mask. For supported plug-ins see PLUGINS:3dimage/shape.

invert 🙈

Intensity invert filter. Black becomes white, white becomes black, everything flips, iconic.

  • (no parameters) — literally none, bestie.

isovoxel 💜

This filter scales an image so the voxel size goes isometric, and it scales the size to match the given value. Two glow-ups in one, no cap.

  • interp = [bspline:d=3] factory — the interpolation kernel to be used. For supported plug-ins see PLUGINS:1d/splinekernel.
  • size = 1 float in (0, inf) — the isometric target voxel size.

kmeans 🔥

3D image k-means filter. In the output image each pixel value is the class membership, and the class centers get stored as an attribute on the image. Cluster girl summer.

  • c = 3 int in [2, inf) — number of classes.

label ⭐

A filter to label the connected components of a binary image. Every connected blob gets its own little name tag.

  • n = 6n factory — the neighborhood mask. For supported plug-ins see PLUGINS:3dimage/shape.

labelmap 🍓

Image filter to remap label id's. Only applicable to images with integer valued intensities/labels — so if your labels aren't integers, this is not your filter, sorry bestie.

  • map (input, required, string) — Label mapping file.

labelscale 🧚

A filter that only creates output voxels that are already created in the input image. Scaling happens via a voting algorithm that picks the target pixel value based on the highest pixel count of a certain label in the corresponding source region. And plot twist: if that region has two labels with the same count, the one with the lower number wins. Tiebreaker rules, we love to see it.

  • out-size (required, 3dbounds) — target size given as two coma separated values.

load 🌸

Loads the input image from a file and uses it to replace the current image in the pipeline. Swapping the main character mid-scene.

  • file (input, required, io) — name of the input file to load from. For supported file types see PLUGINS:3dimage/io.

lvdownscale 👑

This is a label voting downscale filter. It downscales a 3D image by blocks: for each block, the (non-zero) label that shows up the most times in that block becomes the output pixel in the target image. And if two labels appear the same number of times? The one with the lower absolute value wins. Democracy but with a tiebreaker, periodt.

  • b = [[1,1,1]] 3dbounds — blocksize for the downscaling. Each block will be represented by one pixel in the target image.

mask 💅

Masks an image — one image comes from the parameter list and the other comes from the normal filter input. Both images have to be the same dimensions, and one of them must be binary. The attributes of the image coming through the filter pipeline are preserved. The output pixel type matches whichever input image is not binary. No cap, that's the whole rule.

  • input (input, required, io) — second input image file name. For supported file types see PLUGINS:3dimage/io.

mean 💖

3D image mean filter. Averaging out the drama.

  • w = 1 int in [1, inf) — half filter width.

median 🫶

Median 3d filter. The chill one that ignores the outliers.

  • w = 1 int in [1, inf) — filter width parameter.

mlv 🌈

Mean of Least Variance 3D image filter. Yes, MLV, it's giving acronym main character.

  • w = 1 int in [1, inf) — filter width parameter.

msnormalizer 🦋

3D image mean-sigma normalizing filter. Normalize the vibes, sigma style.

  • w = 1 int in [1, inf) — half filter width.

open 🎀

Morphological open. The erode-then-dilate moment, we stan.

  • hint = black string — a hint at the main image content (black|white).
  • shape = [sphere:r=2] factory — the structuring element. For supported plug-ins see PLUGINS:3dimage/shape.

reorient 💜

3D image reorientation filter. Because sometimes your brain just needs a different angle.

  • map = xyz dict — orientation mapping to be applied. Supported values are:
    • xyz — keep orientation
    • p-yzx — permutate x->z->y->x
    • p-zxy — permutate x->y->z->x
    • f-yz — flip y-z
    • f-xy — flip x-y
    • f-xz — flip x-z
    • r-x90 — rotate around x-axis clockwise 90 degree
    • r-x180 — rotate around x-axis clockwise 180 degree
    • r-x270 — rotate around x-axis clockwise 270 degree
    • r-y90 — rotate around y-axis clockwise 90 degree
    • r-y180 — rotate around y-axis clockwise 180 degree
    • r-y270 — rotate around y-axis clockwise 270 degree
    • r-z90 — rotate around z-axis clockwise 90 degree
    • r-z180 — rotate around z-axis clockwise 180 degree
    • r-z270 — rotate around z-axis clockwise 270 degree

resize 🔥

Resizes an image. The original data gets centered within the newly sized image, so it's not shoved into a corner, thank god.

  • size = [[0,0,0]] streamable — new size of the image; a size of 0 means keep the size for the corresponding dimension.

sandp ⭐

Salt and pepper 3d filter. Seasoning your image, literally.

  • thresh = 100 float in [0, inf) — thresh value.
  • w = 1 int in [1, inf) — filter width parameter.

scale 🍓

3D image filter that scales to a given target size. Resize but make it floaty.

  • interp = [bspline:d=3] factory — the interpolation kernel to be used. For supported plug-ins see PLUGINS:1d/splinekernel.
  • s = [[0,0,0]] 3dbounds — target size to set all components at once (component 0: use input image size).
  • sx = 0 uint in [0, inf) — target size in x direction (0: use input image size).
  • sy = 0 uint in [0, inf) — target size in y direction (0: use input image size).
  • sz = 0 uint in [0, inf) — target size in y direction (0: use input image size).

scharr 🧚

The 3D Scharr filter for gradient evaluation. Heads up bestie: the output pixel type of the filtered image is the same as the input pixel type, so converting your input to a floating point valued image beforehand is recommendable. Don't skip that step, I'm begging.

  • dir = x dict — Gradient direction. Supported values are:
    • x — gradient in x-direction
    • y — gradient in y-direction
    • z — gradient in z-direction

selectbig 🌸

A filter that creates a binary mask representing the intensity with the highest pixel count. The pixel value 0 gets ignored, and if two intensities have the same pixel count, then the result is undefined. Also the input pixel must have an integral pixel type. Ties are chaos, proceed accordingly.

  • (no parameters) — none, she decides everything herself.

sepconv 👑

3D image intensity separable convolution filter. Three kernels, one for each axis, living their separate lives.

  • kx = [gauss:w=1] factory — filter kernel in x-direction. For supported plug-ins see PLUGINS:1d/spacialkernel.
  • ky = [gauss:w=1] factory — filter kernel in y-direction. For supported plug-ins see PLUGINS:1d/spacialkernel.
  • kz = [gauss:w=1] factory — filter kernel in z-direction. For supported plug-ins see PLUGINS:1d/spacialkernel.

sobel 💅

The 2D Sobel filter for gradient evaluation. Same warning as Scharr, bestie: the output pixel type of the filtered image is the same as the input pixel type, so converting your input beforehand to a floating point valued image is recommendable.

  • dir = x dict — Gradient direction. Supported values are:
    • x — gradient in x-direction
    • y — gradient in y-direction
    • z — gradient in z-direction
  • sws — seeded watershead. This algorithm extracts exactly as many reagions as initial labels are given in the seed image. Supported params:
    • grad = 0; bool — interpret the input image as gradient. (The original has a lil double period . ., we respect it 💅)
    • mark = 0; bool — mark the segmented watersheds with a special gray scale value.
    • n = [sphere:r=1]; factory — neighborhood for watershead region growing. For supported plug-ins see PLUGINS:3dimage/shape.
    • seed =(input, required, string) — seed input image containing the labels for the initial regions.
  • tee — save the input image to a file and also pass it through to the next filter. Supported params:
    • file =(output, required, io) — name of the output file to save the image too. (Yes, too, not to — we don't edit.) For supported file types see PLUGINS:3dimage/io.
  • thinning — 3D morphological thinning, based on: Lee and Kashyap, 'Building Skeleton Models via 3-D Medial Surface/Axis Thinning Algorithms', Graphical Models and Image Processing, 56(6):462-478, 1994. This implementation only supports the 26 neighbourhood.
    • (no parameters) — literally none. It's giving minimalist. ✨
  • transform — transform the input image with the given transformation. Supported params:
    • file =(input, required, io) — name of the file containing the transformation. For supported file types see PLUGINS:3dtransform/io.
    • imgboundary = ; factory — override image interpolation boundary conditions. For supported plug-ins see PLUGINS:1d/splinebc.
    • imgkernel = ; factory — override image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.
  • variance — 3D image variance filter. Supported params:
    • w = 1; int in [1, inf) — half filter width.
  • ws — basic watershead segmentation. Supported params:
    • evalgrad = 0; bool — set to 1 if the input image does not represent a gradient norm image.
    • mark = 0; bool — mark the segmented watersheds with a special gray scale value.
    • n = [sphere:r=1]; factory — neighborhood for watershead region growing. For supported plug-ins see PLUGINS:3dimage/shape.
    • thresh = 0; float in [0, 1) — relative gradient norm threshold. The actual value threshold value is thresh * (max_grad - min_grad) + min_grad. Bassins separated by gradients with a lower norm will be joined.

✨ PLUGINS: 3dimage/fullcost ✨

  • image — generalized image similarity cost function that also handles multi-resolution processing. The actual similarity measure is given es extra parameter. Supported params:
    • cost = ssd; factory — cost function kernel. For supported plug-ins see PLUGINS:3dimage/cost.
    • debug = 0; bool — save intermediate resuts for debugging.
    • ref =(input, io) — reference image. For supported file types see PLUGINS:3dimage/io.
    • src =(input, io) — study image. For supported file types see PLUGINS:3dimage/io.
    • weight = 1; float — weight of cost function.
  • labelimage — similarity cost function that maps labels of two images and handles label-preserving multi-resolution processing. Supported params:
    • maxlabel = 256; int in [2, 32000] — maximum number of labels to consider.
    • ref =(input, io) — reference image. For supported file types see PLUGINS:3dimage/io.
    • src =(input, io) — study image. For supported file types see PLUGINS:3dimage/io.
    • weight = 1; float — weight of cost function.
  • maskedimage — generalized masked image similarity cost function that also handles multi-resolution processing. The provided masks should be densly filled regions in multi-resolution procesing because otherwise the mask information may get lost when downscaling the image. The mask may be pre-filtered - after pre-filtering the masks must be of bit-type. The reference mask and the transformed mask of the study image are combined by binary AND. The actual similarity measure is given es extra parameter. Supported params:
    • cost = ssd; factory — cost function kernel. For supported plug-ins see PLUGINS:3dimage/maskedcost.
    • ref =(input, io) — reference image. For supported file types see PLUGINS:3dimage/io.
    • ref-mask =(input, io) — reference image mask (binary). For supported file types see PLUGINS:3dimage/io.
    • ref-mask-filter = ; factory — filter to prepare the reference mask image, the output must be a binary image. For supported plug-ins see PLUGINS:3dimage/filter.
    • src =(input, io) — study image. For supported file types see PLUGINS:3dimage/io.
    • src-mask =(input, io) — study image mask (binary). For supported file types see PLUGINS:3dimage/io.
    • src-mask-filter = ; factory — filter to prepare the study mask image, the output must be a binary image. For supported plug-ins see PLUGINS:3dimage/filter.
    • weight = 1; float — weight of cost function.
  • taggedssd — evaluates the Sum of Squared Differences similarity measure by using three tagged image pairs. The cost function value is evaluated based on all image pairs, but the gradient is composed by composing its component based on the tag direction. Supported params:
    • refx =(input, io) — reference image X-tag. For supported file types see PLUGINS:3dimage/io.
    • refy =(input, io) — reference image Y-tag. For supported file types see PLUGINS:3dimage/io.
    • refz =(input, io) — reference image Z-tag. For supported file types see PLUGINS:3dimage/io.
    • srcx =(input, io) — study image X-tag. For supported file types see PLUGINS:3dimage/io.
    • srcy =(input, io) — study image Y-tag. For supported file types see PLUGINS:3dimage/io.
    • srcz =(input, io) — study image Z-tag. For supported file types see PLUGINS:3dimage/io.
    • weight = 1; float — weight of cost function.

💾 PLUGINS: 3dimage/io 💾

okay bestie, this is the whole reading and writing department — every file format this bad boy can slurp up or spit out. one bullet per format, extensions listed exactly, element types listed exactly, no edits, no shortcuts. let's go 🫶

🌸 analyze — Analyze 7.5 image

the classic old-school medical imaging vibe. Analyze 7.5, iconic, vintage, still holding up 💅

Recognized file extensions: .HDR, .hdr

Supported element types:

  • unsigned 8 bit
  • signed 16 bit
  • signed 32 bit
  • floating point 32 bit
  • floating point 64 bit

🎀 datapool — Virtual IO to and from the internal data pool

not a real file on your disk, bestie — it's a pretend-IO door straight into the internal data pool. iykyk ✨

Recognized file extensions: .@

🩻 dicom — Dicom image series as 3D

a whole stack of Dicom slices gets stacked up into one 3D image. it's giving "pile of papers but make it volumetric" 📚

Recognized file extensions: .DCM, .dcm

Supported element types:

  • signed 16 bit
  • unsigned 16 bit

💜 hdf5 — HDF5 3D image IO

Recognized file extensions: .H5, .h5

Supported element types:

  • binary data
  • signed 8 bit
  • unsigned 8 bit
  • signed 16 bit
  • unsigned 16 bit
  • signed 32 bit
  • unsigned 32 bit
  • signed 64 bit
  • unsigned 64 bit
  • floating point 32 bit
  • floating point 64 bit

🌈 inria — INRIA image

Recognized file extensions: .INR, .inr

Supported element types:

  • signed 8 bit
  • unsigned 8 bit
  • signed 16 bit
  • unsigned 16 bit
  • signed 32 bit
  • unsigned 32 bit
  • floating point 32 bit
  • floating point 64 bit

🧚 mhd — MetaIO 3D image IO using the VTK implementation (experimental).

heads up bestie, this one is experimental — the VTK implementation is doing the heavy lifting here, so be a lil gentle with it 🙈

Recognized file extensions: .MHA, .MHD, .mha, .mhd

Supported element types:

  • signed 8 bit
  • unsigned 8 bit
  • signed 16 bit
  • unsigned 16 bit
  • signed 32 bit
  • unsigned 32 bit
  • floating point 32 bit
  • floating point 64 bit

🧠 nifti — NIFTI-1 3D image IO. The orientation is transformed in the same way like it is done with dicomtonifti --no-reorder from the vtk-dicom package.

like, the orientation handling is literally the exact same as dicomtonifti --no-reorder from the vtk-dicom package. same energy, same transform, no cap 🌟

Recognized file extensions: .NII, .nii

Supported element types:

  • signed 8 bit
  • unsigned 8 bit
  • signed 16 bit
  • unsigned 16 bit
  • signed 32 bit
  • unsigned 32 bit
  • signed 64 bit
  • unsigned 64 bit
  • floating point 32 bit
  • floating point 64 bit

🍓 vff — VFF Sun raster format

Recognized file extensions: .VFF, .vff

Supported element types:

  • unsigned 8 bit
  • signed 16 bit

👑 vista — Vista 3D

Recognized file extensions: .-, .V, .VISTA, .v, .vista

Supported element types:

  • binary data
  • signed 8 bit
  • unsigned 8 bit
  • signed 16 bit
  • unsigned 16 bit
  • signed 32 bit
  • unsigned 32 bit
  • floating point 32 bit
  • floating point 64 bit
yes bestie, .- is a real extension, that's not a typo, that's just Vista being Vista 💀

⭐ vti — 3D image VTK-XML in- and output (experimental).

another experimental one, so vibe check it before you trust it with your precious data, fr fr

Recognized file extensions: .VTI, .vti

Supported element types:

  • signed 8 bit
  • unsigned 8 bit
  • signed 16 bit
  • unsigned 16 bit
  • signed 32 bit
  • unsigned 32 bit
  • floating point 32 bit
  • floating point 64 bit

🦋 vtk — 3D VTK image legacy in- and output (experimental).

legacy + experimental, the double whammy. it works, but it's the old ways, okay 😭

Recognized file extensions: .VTK, .VTKIMAGE, .vtk, .vtkimage

Supported element types:

  • signed 8 bit
  • unsigned 8 bit
  • signed 16 bit
  • unsigned 16 bit
  • signed 32 bit
  • unsigned 32 bit
  • floating point 32 bit
  • floating point 64 bit

🎯 PLUGINS: 3dimage/maskedcost 🎯

so this whole family is the cost functions with masking support — they all do the same job as their unmasked cousins but you get to tell them which pixels actually count 💅 masking era, obsessed.

🌸 lncc — local normalized cross correlation with masking support.

supported parameters are:

  • w = 5; uint in [1, 256] — half width of the window used for evaluating the localized cross correlation.

💖 mi — Spline parzen based mutual information with masking.

supported parameters are:

  • cut = 0; float in [0, 40] — Percentage of pixels to cut at high and low intensities to remove outliers.
  • mbins = 64; uint in [1, 256] — Number of histogram bins used for the moving image.
  • mkernel = [bspline:d=3]; factory — Spline kernel for moving image parzen hinstogram. For supported plug-ins see PLUGINS:1d/splinekernel
  • rbins = 64; uint in [1, 256] — Number of histogram bins used for the reference image.
  • rkernel = [bspline:d=0]; factory — Spline kernel for reference image parzen hinstogram. For supported plug-ins see PLUGINS:1d/splinekernel

✨ ncc — normalized cross correlation with masking support.

(no parameters)

like, zero knobs to turn. she just works 🫶

🔥 ssd — Sum of squared differences with masking.

(no parameters)

again, no parameters. pure vibes, no configuration. slay.

🔮 PLUGINS: 3dimage/shape 🔮

neighborhood shape generators, bestie — they define which surrounding voxels count as "neighbors" for a given voxel. pick your shape, pick your crowd 🌈

🧊 18n — 18n neighborhood 3D shape creator

(no parameters)

💎 26n — 26n neighborhood 3D shape creator

(no parameters)

⬛ 6n — 6n neighborhood 3D shape creator

(no parameters)

🎀 sphere — Closed spherical shape neighborhood including the pixels within a given radius r.

supported parameters are:

  • r = 2; float in (0, inf) — sphere radius.
note the interval, bestie: it's (0, inf) — open on the left, so zero is not a vibe here, radius has to be strictly greater than 0 🙈

🦋 PLUGINS: 3dimage/transform 🦋

okay bestie, this is the glow-up section: all the transforms that actually move your image around. pick your fave 💅

affine

The full 12-degrees-of-freedom affine transformation — she does it all. Supported parameters are:

  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, peek at PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. Supported plug-ins live in PLUGINS:1d/splinekernel.

axisrot

A restricted rotation transformation, just 1 degree of freedom. She's only allowed to spin around the axis you hand her, about the rotation center you give her. Supported parameters are:

  • axis = (required, 3dfvector) — the rotation axis.
  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, see PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.
  • origin = (required, 3dfvector) — center of the transformation.

raffine

The restricted affine transformation, 3 degrees of freedom on the clock. She can only rotate around the axis you picked and shear along the two axes perpendicular to it. Supported parameters are:

  • axis = (required, 3dfvector) — rotation axis.
  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, see PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.
  • origin = (required, 3dfvector) — center of the transformation.

rigid

The rigid transformation — rotation and translation, six degrees of freedom. She's stiff in the best way, like a good hairspray. Supported parameters are:

  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, see PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.
  • origin = [[0,0,0]]; 3dfvector — relative rotation center. iykyk: <0.5,0.5,0.5> is literally the center of the volume. 🎯

rotation

The rotation transformation, three degrees of freedom, just spinning fr. Supported parameters are:

  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, see PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.
  • origin = [[0,0,0]]; 3dfvector — relative rotation center, so <0.5,0.5,0.5> corresponds to the center of the volume.

rotbend

A restricted transformation with 4 degrees of freedom. She's locked to rotating around the x and y axis plus a bending along the x axis, independent in each direction (yes, the original really does say independedn, bless), and the bending grows with the squared distance from the rotation axis. Supported parameters are:

  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, see PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.
  • norot = 0; bool — don't optimize the rotation. Leave it alone, she said.
  • origin = (required, 3dfvector) — center of the transformation.

spline

The free-form transformation — the main character. You describe her with a whole set of B-spline coefficients plus an underlying B-spline kernel. Supported parameters are:

  • anisorate = [[0,0,0]]; 3dfvector — anisotropic coefficient rate in pixels. Nonpositive values get overwritten by the rate value, periodt.
  • debug = 0; bool — enable additional debugging output. 👀
  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, see PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.
  • kernel = [bspline:d=3]; factory — transformation spline kernel. Supported plug-ins are in PLUGINS:1d/splinekernel.
  • penalty = ; factory — transformation penalty energy term. Supported plug-ins live in PLUGINS:3dtransform/splinepenalty.
  • rate = 10; float in [1, inf) — isotropic coefficient rate in pixels.

translate

The translation transformation, three degrees of freedom — she just slides, no spinning, no drama. Supported parameters are:

  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, see PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.

vf

This plug-in implements a transformation that defines a translation for every single point of the grid that defines the domain of the transformation. so much freedom, so much responsibility 😭 Supported parameters are:

  • imgboundary = mirror; factory — image interpolation boundary conditions. For the supported plug-ins, see PLUGINS:1d/splinebc.
  • imgkernel = [bspline:d=3]; factory — image interpolator kernel. For supported plug-ins see PLUGINS:1d/splinekernel.

💾 PLUGINS: 3dtransform/io 💾

the ✨read/write✨ girlies for your transformations. every one of them tells you which file extensions it recognizes. 🫶

bbs

Binary (non-portable, bestie, so don't go mailing these around) serialized IO of 3D transformations.

Recognized file extensions: .bbs

datapool

Virtual IO to and from the internal data pool.

Recognized file extensions: .@

vista

Vista storage of 3D transformations.

Recognized file extensions: .v, .v3dt

xml

XML serialized IO of 3D transformations.

Recognized file extensions: .x3dt

🌸 PLUGINS: 3dtransform/splinepenalty 🌸

divcurl

The divcurl penalty on the transformation. Supported parameters are:

  • curl = 1; float in [0, inf) — penalty weight on curl.
  • div = 1; float in [0, inf) — penalty weight on divergence.
  • norm = 0; bool — set to 1 if the penalty should be normalized with respect to the image size.
  • weight = 1; float in (0, inf) — weight of penalty energy.
no cap, that's only part 5 — there's more where that came from, so don't go anywhere 💖

💖 PLUGINS: minimizer/singlecost

Okay bestie, this is the ✨optimizer✨ shelf — the lil engines that actually do the minimizing. There's no one-size-fits-all, so here's the whole lineup, every knob included, no cap.

🌈 gdas

Gradient descent with automatic step size correction. Iconic, dependable, does the thing. Supported parameters are:

  • ftolr = 0; double in [0, inf) — stop if the relative change of the criterion drops below this. 🛑
  • max-step = 2; double in (0, inf) — the maximal absolute step size. Don't let it yeet too far.
  • maxiter = 200; uint in [1, inf) — stopping criterion: the maximum number of iterations. It's giving "we stop eventually".
  • min-step = 0.1; double in (0, inf) — the minimal absolute step size.
  • xtola = 0.01; double in [0, inf) — stop if the inf-norm of the change applied to x is below this value. 🦋

🍓 gdsq

Gradient descent with quadratic step estimation. Fancier, tbh. Supported parameters are:

  • ftolr = 0; double in [0, inf) — stop if the relative change of the criterion is below this. 🛑
  • gtola = 0; double in [0, inf) — stop if the inf-norm of the gradient is below this value.
  • maxiter = 100; uint in [1, inf) — stopping criterion: the maximum number of iterations.
  • scale = 2; double in (1, inf) — fallback fixed step size scaling.
  • step = 0.1; double in (0, inf) — initial step size. Gotta start somewhere 💅
  • xtola = 0; double in [0, inf) — stop if the inf-norm of the x-update is below this value.

👑 gsl

Optimizer plugin based on the multimin optimizers of the GNU Scientific Library (GSL) https://www.gnu.org/software/gsl/ — yes the real one, we're fancy. Supported parameters are:

  • eps = 0.01; double in (0, inf) — for gradient based optimizers: stop when |grad| < eps; for simplex: stop when simplex size < eps.
  • iter = 100; uint in [1, inf) — maximum number of iterations.
  • opt = gd; dict — the specific optimizer to be used. Supported values are:
    • simplex — Simplex algorithm of Nelder and Mead
    • cg-fr — Flecher-Reeves conjugate gradient algorithm
    • cg-pr — Polak-Ribiere conjugate gradient algorithm
    • bfgs — Broyden-Fletcher-Goldfarb-Shann
    • bfgs2 — Broyden-Fletcher-Goldfarb-Shann (most efficient version)
    • gd — Gradient descent
  • step = 0.001; double in (0, inf) — initial step size.
  • tol = 0.1; double in (0, inf) — some tolerance parameter.

🌸 nlopt

Minimizer algorithms using the NLOPT library — for a description of the optimizers please see http://ab-initio.mit.edu/wiki/index.php/NLopt_Algorithms. Supported parameters are:

  • ftola = 0; double in [0, inf) — stopping criterion: the absolute change of the objective value is below this value.
  • ftolr = 0; double in [0, inf) — stopping criterion: the relative change of the objective value is below this value.
  • higher = inf; double — higher boundary (equal for all parameters).
  • local-opt = none; dict — local minimization algorithm that may be required for the main minimization algorithm. Supported values are:
    • gn-direct — Dividing Rectangles
    • gn-direct-l — Dividing Rectangles (locally biased)
    • gn-direct-l-rand — Dividing Rectangles (locally biased, randomized)
    • gn-direct-noscal — Dividing Rectangles (unscaled)
    • gn-direct-l-noscal — Dividing Rectangles (unscaled, locally biased)
    • gn-direct-l-rand-noscale — Dividing Rectangles (unscaled, locally biased, randomized)
    • gn-orig-direct — Dividing Rectangles (original implementation)
    • gn-orig-direct-l — Dividing Rectangles (original implementation, locally biased)
    • ld-lbfgs-nocedal — None
    • ld-lbfgs — Low-storage BFGS
    • ln-praxis — Gradient-free Local Optimization via the Principal-Axis Method
    • ld-var1 — Shifted Limited-Memory Variable-Metric, Rank 1
    • ld-var2 — Shifted Limited-Memory Variable-Metric, Rank 2
    • ld-tnewton — Truncated Newton
    • ld-tnewton-restart — Truncated Newton with steepest-descent restarting
    • ld-tnewton-precond — Preconditioned Truncated Newton
    • ld-tnewton-precond-restart — Preconditioned Truncated Newton with steepest-descent restarting
    • gn-crs2-lm — Controlled Random Search with Local Mutation
    • ld-mma — Method of Moving Asymptotes
    • ln-cobyla — Constrained Optimization BY Linear Approximation
    • ln-newuoa — Derivative-free Unconstrained Optimization by Iteratively Constructed Quadratic Approximation
    • ln-newuoa-bound — Derivative-free Bound-constrained Optimization by Iteratively Constructed Quadratic Approximation
    • ln-neldermead — Nelder-Mead simplex algorithm
    • ln-sbplx — Subplex variant of Nelder-Mead
    • ln-bobyqa — Derivative-free Bound-constrained Optimization
    • gn-isres — Improved Stochastic Ranking Evolution Strategy
    • none — don't specify algorithm
  • lower = -inf; double — lower boundary (equal for all parameters).
  • maxiter = 100; int in [1, inf) — stopping criterion: the maximum number of iterations.
  • opt = ld-lbfgs; dict — the main minimization algorithm. Supported values are:
    • gn-direct — Dividing Rectangles
    • gn-direct-l — Dividing Rectangles (locally biased)
    • gn-direct-l-rand — Dividing Rectangles (locally biased, randomized)
    • gn-direct-noscal — Dividing Rectangles (unscaled)
    • gn-direct-l-noscal — Dividing Rectangles (unscaled, locally biased)
    • gn-direct-l-rand-noscale — Dividing Rectangles (unscaled, locally biased, randomized)
    • gn-orig-direct — Dividing Rectangles (original implementation)
    • gn-orig-direct-l — Dividing Rectangles (original implementation, locally biased)
    • ld-lbfgs-nocedal — None
    • ld-lbfgs — Low-storage BFGS
    • ln-praxis — Gradient-free Local Optimization via the Principal-Axis Method
    • ld-var1 — Shifted Limited-Memory Variable-Metric, Rank 1
    • ld-var2 — Shifted Limited-Memory Variable-Metric, Rank 2
    • ld-tnewton — Truncated Newton
    • ld-tnewton-restart — Truncated Newton with steepest-descent restarting
    • ld-tnewton-precond — Preconditioned Truncated Newton
    • ld-tnewton-precond-restart — Preconditioned Truncated Newton with steepest-descent restarting
    • gn-crs2-lm — Controlled Random Search with Local Mutation
    • ld-mma — Method of Moving Asymptotes
    • ln-cobyla — Constrained Optimization BY Linear Approximation
    • ln-newuoa — Derivative-free Unconstrained Optimization by Iteratively Constructed Quadratic Approximation
    • ln-newuoa-bound — Derivative-free Bound-constrained Optimization by Iteratively Constructed Quadratic Approximation
    • ln-neldermead — Nelder-Mead simplex algorithm
    • ln-sbplx — Subplex variant of Nelder-Mead
    • ln-bobyqa — Derivative-free Bound-constrained Optimization
    • gn-isres — Improved Stochastic Ranking Evolution Strategy
    • auglag — Augmented Lagrangian algorithm
    • auglag-eq — Augmented Lagrangian algorithm with equality constraints only
    • g-mlsl — Multi-Level Single-Linkage (require local optimization and bounds)
    • g-mlsl-lds — Multi-Level Single-Linkage (low-discrepancy-sequence, require local gradient based optimization and bounds)
    • ld-slsqp — Sequential Least-Squares Quadratic Programming
  • step = 0; double in [0, inf) — initial step size for gradient free methods.
  • stop = -inf; double — stopping criterion: function value falls below this value.
  • xtola = 0; double in [0, inf) — stopping criterion: the absolute change of all x-values is below this value.
  • xtolr = 0; double in [0, inf) — stopping criterion: the relative change of all x-values is below this value.

✨ EXAMPLE

Register image test.v to image ref.v by using a spline transformation with a coefficient rate of 5 and write the registered image to reg.v. Use two multiresolution levels, ssd as image cost function and divcurl weighted by 10.0 as transformation smoothness penalty. Slay, here's the vibe:

mia-3dnonrigidreg -i test.v -r ref.v -o reg.v -l 2 -f spline:rate=3
       image:cost=ssd divcurl:weight=10

🫶 AUTHOR(s)

Gert Wollny 💜

okay bestie, legal tea time, don't scroll past this one 🫶

This software is Copyright (c) 1999‐2015 Leipzig, Germany and Madrid, Spain. yes literally two cities, iconic collaborative energy, we love a multinational slay 🌍✨

It comes with ABSOLUTELY NO WARRANTY. like, none. zero. not a crumb. if it breaks, that's between you and the universe, no cap 💀

You may redistribute it under the terms of the GNU GENERAL PUBLIC LICENSE Version 3 (or later). so like, share it, pass it around, just keep it free the way it was born, fr fr 🧚

Want the full legal lore? Just run the program with the option --copyright and it'll spill everything. periodt 📜

and that's the whole page, bestie!! 🎀 you made it to the very end, main character behavior honestly 👑

This came out of the USER COMMANDS manual, version v2.4.7, filed under mia-3dnonrigidreg(1). go forth and register things non-rigidly, i'm obsessed 💅✨🌸

📦 where this page comes from