Image batch processing tools.

The image processing pipeline loads the projection images, processes each image step by step, and then saves it in the desired output format. Processing steps can be freely added to the pipeline. Those have to be configured and set up before running the pipeline.

Image conversion

Pipeline concept

The required minimum set of parameters are an input file pattern and an output file pattern. As illustrated in the following picture, a file pattern is a string that specifies a single file name (for a single 2D image or a raw chunk of multiple images), or a stack of 2D images using the %[N]d placeholder for a number that contains [N] digits, e.g. %04d for the numbers from 0000 to 9999.

Input and output files

Any kind of image file (input, output, flat fields) can be specified by creating ImageStack objects. These objects will later be passed to the processing pipeline or to processing step configurations.

In the following example, a 16 bit unsigned integer raw data volume file that contains 21 slices of 150x150 pixels is converted into a stack of 21 TIFF files, each with a 32 bit float data type.

# -*- coding: UTF-8 -*-
# File: examples/processing/01_simple_pipeline.py

from ctsimu.image import ImageStack
from ctsimu.processing.pipeline import Pipeline

# All projection images are in one raw chunk:
projectionFiles = ImageStack(
    filePattern="tetrahedron/projections/tetra_projections.raw",
    width=150,
    height=150,
    slices=21,
    dataType="uint16",
    byteOrder="little"
)

# Save as individual TIFF images:
outputFiles = ImageStack(
    filePattern="tetrahedron/projections/tetra_%04d.tif",
    dataType="float32"
)

# Create and run pipeline:
pipe = Pipeline(
    inputFileStack=projectionFiles,
    outputFileStack=outputFiles
)
pipe.run()

For TIFF files, the data type is determined from the header information when reading existing files, but the given value is obeyed when they are saved. This allows to convert the data type from one to another. For RAW files, this information must be provided for all input. Upon saving, RAW and TIFF output files automatically get the input file parameters if no output parameters are provided.

The minimum set of parameters required to set up a Pipeline are the input and output images. This way, the pipeline can be used to convert images from one format to another. Any parameters that are not specified for the output images (such as data type and byte order) will be taken from the input file parameters.

Image processing

Flat-field correction

Images can be processed by adding a processing Step (or several to create a processing chain) to the Pipeline.

The following example performs a dark-field and flat-field correction using existing dark and bright free-beam images. It uses the processing step called Step_FlatFieldCorrection.

# -*- coding: UTF-8 -*-
# File: examples/processing/02_flatfield_correction.py

from ctsimu.image import ImageStack
from ctsimu.processing.pipeline import Pipeline
from ctsimu.processing.flat_field import Step_FlatFieldCorrection

# All projection images are in one raw chunk:
projectionFiles = ImageStack(
    filePattern="tetrahedron/projections/tetra_projections.raw",
    width=150,
    height=150,
    slices=21,
    dataType="uint16",
    byteOrder="little"
)

# Save as individual TIFF images:
outputFiles = ImageStack(
    filePattern="tetrahedron/projections/corrected/tetra_%04d.tif",
    dataType="float32"
)

# Create a pipeline:
pipe = Pipeline(
    inputFileStack=projectionFiles,
    outputFileStack=outputFiles
)

# 3 bright free-beam images for flat-field correction:
flatField = ImageStack(
    "tetrahedron/projections/tetra_flat_%04d.raw",
    width=150,
    height=150,
    dataType="uint16",
    byteOrder="little"
)

# One dark image:
darkField = ImageStack(
    "tetrahedron/projections/tetra_dark.raw",
    width=150,
    height=150,
    dataType="uint16",
    byteOrder="little"
)

# Create flat-field correction processing step:
ffCorrection = Step_FlatFieldCorrection(
    flatFileStack=flatField,
    darkFileStack=darkField,
    rescaleFactor=50000,
    offsetAfterRescale=0
)

# Add the processing step to the pipeline
# and run the processing:
pipe.addStep(ffCorrection)
pipe.run()

If a stack of multiple images is provided either for flat or dark images, the mean image of this stack will be used for the flat/dark field correction.

A rescaleFactor can be provided to rescale the projection gray values after they have been normalized. This is especially necessary if your output files will have an integer data type, as the gray values will typically be in the interval [0, 1] after a flat field correction.

Binning

For binning, the bin size has to be specified in x and y direction, as well as the binning operation (possible values: "mean", "min", "max", "sum").

# -*- coding: UTF-8 -*-
# File: examples/processing/03_binning.py

from ctsimu.image import ImageStack
from ctsimu.processing.pipeline import Pipeline
from ctsimu.processing.binning import Step_Binning

# All projection images are in one raw chunk:
projectionFiles = ImageStack(
    filePattern="tetrahedron/projections/tetra_projections.raw",
    width=150,
    height=150,
    slices=21,
    dataType="uint16",
    byteOrder="little"
)

# Save as individual TIFF images:
outputFiles = ImageStack(
    filePattern="tetrahedron/projections/binned/tetra_%04d.tif",
    dataType="float32"
)

# Create a pipeline:
pipe = Pipeline(
    inputFileStack=projectionFiles,
    outputFileStack=outputFiles
)

# Create binning step:
binning = Step_Binning(
    binSizeX=2,
    binSizeY=2,
    binningOperation='mean'
)

# Add the processing step to the pipeline
# and run the processing:
pipe.addStep(binning)
pipe.run()

# -*- coding: UTF-8 -*-
"""Image batch processing tools.

The image processing pipeline loads the projection images, processes each image step by step, and then saves it in the desired output format. Processing steps can be freely added to the pipeline. Those have to be configured and set up before running the pipeline.

.. include:: ./documentation.md
"""

from . import *

Sub-modules

ctsimu.processing.binning

ctsimu.processing.flat_field

ctsimu.processing.median

ctsimu.processing.noise

ctsimu.processing.pipeline

ctsimu.processing.smoothing

ctsimu.processing.step

ctsimu.processing.transform