StitchingRigid

Stitching module for aligning and stitching data sets ridgidly.

The module provides base classes and routines for stitching images. The StichingWobbly module builds on this module.

class Alignment(pre=None, post=None, shift=None, displacement=None, quality=None)

Bases: AlignmentBase

Class to handle rigid alignments between two adjacent sources.

mip_axis(axis=None, max_shifts=None)

A axis for maximum projections.

plot(*args, **kwargs)

Plots this alignment

property displacement

The displacement between the two sources given their positions and the alignment shift.

Returns

displacmeentarray of int

The displacement between the sources.

property name

property quality

The quality of this alignment.

Returns

qualityfloat

The quality of this alignment.

property shift

The additional shift between the source positions that better aligns them.

Returns

shiftarray of int

The additional shift between the source positions that better aligns them.

class AlignmentBase(pre=None, post=None)

Bases: object

Base class to handle alignments between two adjacent sources.

copy()

overlay(**kwargs)

overlay_mip(*args, **kwargs)

Overlays this alignment using max intensity projection.

overlay_overlap(max_shifts=0)

plot(*args, **kwargs)

Plots this alignment

plot_mip(*args, **kwargs)

Plots this alignment using max intensity projection.

plot_overlap(**kwargs)

plot_overlay(**kwargs)

property ndim

Dimension of the alignment sources.

Returns

ndimint

The dimension of the sources.

property post

The second source that contributes to this alignment.

Returns

sourceSource classes

The second source that contribute to this alignment.

property pre

The first source that contributes to this alignment.

Returns

sourceSource classes

The first source that contribute to this alignment.

property sources

The sources that contribute to this alignment.

Returns

sourceslist of Source classes

The sources that contribute to this alignment.

class Layout(sources, alignments=None, position=None, shape=None, dtype=None, order=None, location=None)

Bases: SourceRegion, AbstractSource

Base class to handle the layout of multiple sources.

align(max_shifts=10, clip=None, background=None, processes=None, verbose=False)

Align the sources.

align_axis(depth=10, max_shifts=10, axis=None, axis_range=None, clip=None, background=None, processes=None, verbose=False)

Aligns sources in a layout along a single axis only.

Arguments

layout: Layout class

The layout in which to align the 3d sources in z-direction.

depthint or list of ints

The approximate overlaps of the sources in the tiling dimensions to use for mip projection when aligning the axis.

max_shiftstuple of ints

The minmal and maximal shifts along all axes consider.

axisint

The axis to aling the sources along.

axis_rangetuple of int or None

If not None, use only a sub set of the axis range to speed up processing.

clipnumber or None

If not None, clip the soruces at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

processesint or ‘serial’

Number of processor to use for parallel processing, if ‘serial’ process in serial.

verbosebool

Print progress information.

array_along_axis(sink=None, coordinate=None, axis=2)

Returns the stitched data

Arguments

sinksink specification or None

The sink to write the result to. If None return as array.

coordinateint

The coordinate at which to take the slice.

axisint

The axis to take the slice in.

Returns

dataarray or sink

The stitched array or sink.

as_real()

as_virtual()

Return virtual source without array data to pass in parallel processing.

Returns

sourceSource class

The source class without array data.

change_source_location(expression, substitutions)

Change the sources to point to a new location.

Arguments

expressionstr

Tag expression of source names with additional substitution tags.

substitutionsdict

A substitution dictionary of the form {tag_name : value}, specifying how to replace the substitution tags.

Note

This function is useful to stitch other color channels of imagining data using the same alignments.

change_sources(sources)

changes the sources of this layout.

Arguments

sourceslist of sources

The new sources.

Note

This allows to stitch other color channels with the same alignment.

connected()

Returns True if the alignments form a single connected component.

Returns

connectedbool

True if the alignments form a single connected component.

connected_components(min_quality=None, with_sources=False)

Determines the connected components of the layout.

Arguments

min_qualityfloat, tuple of floats or None

The minimal quality needed to include an alignment in the calculation.

with_sourcesbool

If True, also return the sources in each component.

Returns

componentslist of list of Alignment classes

The connected components of the alignments.

component_sourceslist of list of Source classes

The sources in each compoenent.

embedding()

Splits the set of co-axial sources into a minimal set of non-overlaping regions.

Returns

shapetuple of int

The shape that encapsulates all the regions.

positiontuple of int

The lowest corner of all the regions.

regionslist of Region classes.

The regions of different overlaps of the individual sources.

Note

The result can be used to stitch the images.

layout_from_region(region=None, position=None, shape=None, lower=None, upper=None)

Returns a layout with only the sources needed to construct the specified region

Returns

layoutLayout class

The reduced layout needed to cover the region.

load(filename)

Loads the layout specifications from a file.

lower_to_origin()

Moves the sources so that the lower corner is at the origin.

overlay(colors=None, percentile=98, normalize=True, coordinate=None, axis=2)

Overlays the sources to check their placement.

Arguments

colorslist of tuple of floats or color names

The optional RGB colors to use.

percentileint

Use this percentile as upper cutoff in the resulting image to enhance contrast.

normalizebool

If True normalize image to floats between 0 and 1.

coordinateint or None

Optional coordinate at which to take a slice.

axisint

Optional axis to take the slice in.

Returns

imagearray

A color image.

place(method='optimization', lower_to_origin=False, processes=None, verbose=False, min_quality=None)

Optimizes positions of the sources in this layout.

place_axis(axis=None, method='optimization', min_quality=None, lower_to_origin=False, verbose=False)

Places the sources in a layout along a single axis only.

Arguments

axis: int

The axis which to place the sources along.

method‘optimization’ or ‘tree’

The method to use to place the sources.

min_qualityfloat

The minimal quality of the alignment.

lower_to_originbool

If True the lower corner of the aligned images is set to zero.

plot(colors=None, percentile=98, normalize=True, color_ids=None, coordinate=None, axis=2)

Plots overlayed sources to check their placement.

Arguments

colorslist of tuple of floats or color names

The optional RGB colors to use.

percentileint

Use this percentile as upper cutoff in the resulting image to enhance contrast.

normalizebool

If True normalize image to floats between 0 and 1.

color_idslist of ints

Use specific color ids for the sources contributing to the layout.

coordinateint or None

Optional coordinate at which to take a slice.

axisint

Optional axis to take the slice in.

Returns

imagearray

A color image.

plot_alignments(cmap=<matplotlib.colors.LinearSegmentedColormap object>, annotate=True, axes=[0, 1])

Overlays and plots regions to check the alignment of this layout.

Arguments

cmapcolormap

The color map to use to color the regions.

annotatebool

Use annotaton or not.

axestuple of ints

Axes to use if sources are larger than 2d.

plot_regions(cmap=<matplotlib.colors.LinearSegmentedColormap object>, annotate=True, axes=[0, 1])

Overlays and plots regions to check the alignment of this layout.

Arguments

cmapcolormap

The color map to use to color the regions.

annotatebool

Use annotaton or not.

axestuple of ints

Axes to use if sources are larger than 2d.

remove_source(source)

Removes a source from this Layout.

Arguments

sourceint, Source class or list of ints or Source classes

The list of source classes to remove from this layout.

Note

The alignments are cleaned in a consistent way when this routine is used.

replace_source_location(match, replace, method='expression')

Change the sources to point to a new location.

Arguments

matchstr or Expression

Expression of source names to match and substitute.

replacestr or Expression

Expression to replace source names with.

Note

This function is useful to stitch other color channels of imagining data using the same alignments.

save(filename)

Saves the layout to a file.

set_source_positions(positions=None, sources=None, update_alignments=False)

Sets the positions of the sources.

Arguments

positionslist of tuple of ints or None

The new positions of the sources, if None infer a consistent solution from the alignments.

sourceslist of Source classes

If only a subset of positions is given, this list represents the sources of those positions.

update_alignmentsbool

If True, also update the alignments shifts to match the new positions.

sink_slicing()

Returns the slice of this layout’s data in an underlying sink.

Returns

slicelist of slice objects

The slice to use if this layout is placed in an underling sink.

Note

Positions below zero are cut off as well as above the shape.

slice_along_axis(coordinate, axis=2)

Returns a layout corresponding to a slice along a single axis in this layout.

Arguments

coordinateint

The coordinate at which to take the slice.

axisint

The axis to take the slice in.

Returns

layoutSlicedLayout class

The sliced layout.

sort_sources_by_position()

Sorts the sources of this layout by their current position.

source_index(source)

The id of a source in the list of sources.

Arguments

source : Source class

Returns

idint or None

Position of the source in the sources list, None if not found.

source_positions(sources=None)

Returns the positions of the sources.

Returns

positionslist of tuples of ints

The source positions.

sources_as_real()

sources_as_virtual()

stitch(sink=None, method='interpolation', processes=None, verbose=False)

Stitches the sources according to this layout.

Arguments

sinksink specification or None

The sink to write the result to.

methodstr

The method to use for the stitching: ‘interpolation’, ‘max’, ‘min’, ‘mean’

Returns

stitchedarray or sink

The stitched array or sink.

update_alignments_from_sources()

Updates the alignments from the source positions.

update_sources_from_alignments()

Updates the source positions from the alignments.

property alignments

The alignments in the layout.

Returns

alignmentslist

List of the alignments in this layout.

property array

Returns the stitched data

Arguments

sinksink specification or None

The sink to write the result to. If None return as array.

Returns

dataarray or sink

The stitched array or sink.

property dtype

Data type of the sources in the layout.

Returns

dtypedtype

Data type of the sources in this layout.

property location

The location of the layout when written.

Returns

locationstr

The location of the layout when written.

property lower

Calculates the lower position of the entire layout.

Returns

lowertuple of ints

The lower position of the full layout.

property n_alignments

Number of alignments in this layout.

Returns

n_alignmentsint

Number of alignments in this layout.

property n_sources

Number of sources in the layout.

Returns

n_sourcesint

Number of sources in this layout.

property ndim

Dimension of the alignment sources.

Returns

ndimint

The dimension of the sources.

property order

The contiguous order of the source.

Returns

orderorder

The contiguous order of the source.

property position

Returns the lower position of the layout.

Returns

positiontuple of ints

The position of the lower corner of this layout.

property shape

Shape of the layout.

Returns

shapetuple of int

The shape of the layout when stitching together all the sources.

property sources

The sources in the layout.

Returns

sourceslist

List of the sources in this layout.

property upper

Calculates the upper position of the entire layout.

Returns

uppertuple of ints

The upper position of the full layout.

class Overlap(position=None, shape=None, lower=None, upper=None, sources=None)

Bases: Region

Class to handle overlapping regions of aligned sources.

plot()

Plots the overlap region.

Returns

plotDataViewer

The plot of the overlap.

source_arrays()

Returns the data arrays of the sources in this region

Returns

arrayslist of arrays

The arrays of all the sources that overlap in this region.

source_slicings()

Returns the slices of this overlap region of the contributing sources.

Returns

sliceslist of list of slice objects

The slice specifications for the sources.

property sources

The sources that contribute to this overlap region.

Returns

sourceslist of Source classes

The sources that contribute to this region.

class Region(position=None, shape=None, lower=None, upper=None)

Bases: object

Class to handle rectangular regions storing positional information.

coordinate_from_local(loacl_coordinate, axis)

Converts a local coordainte along an axis to the non-local coordinate.

Arguments

local_coordinateint

The local coordinate along the axis.

axisint

The axis of the coordiante.

Returns

coordinateint

The non-local coordainte.

coordinate_to_local(coordinate, axis)

Converts a coordinate along an axis to the a local coordinate.

Arguments

coordinateint

The non-local coordinate along the axis.

axisint

The axis of the coordiante.

Returns

loacl_coordinatetuple of ints, or int

The local coordinate within this region.

copy()

local_slicing(source=None, position=None)

Returns the slice of this region in a source or from a position.

Arguments

sourceSource class

Source at which this region should be sliced.

positiontuple of ints

Position of the lower corner of the sink.

Returns

slicelist of slice objects

The slice specifications for this region in a source.

Note

This routine assumes that the region is within the source. No boundary checks are performed.

position_from_local(local_position)

Converts a position given in local coordiantes to the non-local position.

Arguments

local_positiontuple of ints

The local position within the region.

Returns

positiontuple of ints

The non-local position.

position_to_local(position)

Converts a position to the a local position wrt to the sources origin.

Arguments

positiontuple of ints

The non-local position.

Returns

loacl_positiontuple of ints

The local position within this region.

property extent

The difference between upper and lower corner.

Returns

extenttuple of int

The difference between upper and lower corner.

Note

The extent can differ from the shape in case the source is bended or wobbly.

property lower

The lower corner of the source’s placement.

Returns

lowerarray of int

The coordinates of the lower corner of the source’s placment.

property ndim

The dimension of the source.

Returns

ndimint

The dimension of the source.

property origin

The origin of this region, i.e. its positively rectified position.

Returns

origintuple of ints

The rectified position, i.e. coordiantes below zero are set to zero.

property position

The position of the region.

Returns

positiontuple of ints

The position of the region.

property shape

The shape of the region.

Returns

shapetuple of int

The shape of the layout.

property upper

The upper corner of the source’s placement.

Returns

upperarray of int

The coordinates of the upper corner of the source’s placment.

class Slice(source, position=None, tile_position=None, slicing=None)

Bases: Slice, SourceRegion

Class to handle a slice of a stitchable source.

as_real()

as_virtual()

Returns a virtual handle to this source striped of any big array data useful for parallel processing.

Returns

sourceSource class

The source class with out any cached array data.

Note

The slicing structure is kept here to be able to appropiately take slices in a source when processsing in parallel.

property id

property identifier

property position

Returns the indices of the lower corner of this slice in the underlying source.

Returns

positiontuple of int

The coordinates of the lower corner of this slice within the source.

property position_unsliced

Returns the position of this slice in the underlying space taking into account the source position.

Returns

positiontuple of ints or int

The position of the slice in the higher dimensional space of the source.

property tile_position

class Source(source=None, position=None, tile_position=None)

Bases: SourceRegion, AbstractSource

Class to handle basic data sources in a layout for stitching.

as_real()

as_virtual()

Return virtual source without array data to pass in parallel processing.

Returns

sourceSource class

The source class without array data.

plot()

slice_along_axis(coordinate=None, local_coordinate=None, axis=2)

Slice this source at a coordinate along an axis.

Arguments

coordinateint

The coordinate at which to take the slice.

local_coordinateint

The local coordinate in the underlying source along the slice axis.

axisint

The axis to take the slice in.

Returns

sourceSlicedSource class

The sliced source.

Note

Either coordiante or local_coordinate must be given.

counter = 0

Counter for the sources used to create unique ids.

property id

The source id.

Returns

idint

The id of the source.

Note

Parallel processing changes pointers, this id can be used to identify the same source.

property identifier

property location

The location of the source’s data.

Returns

locationstr or None

Returns the location of the data source or None if there is none.

property name

The name of this source.

Returns

namestr

Name of this source.

property source

The underlying IO source.

property tile_position

Optional position on a grid.

Returns

tile_positiontuple of int

The tile position of this source on a grid.

class SourceRegion(position=None, shape=None, lower=None, upper=None)

Bases: Region

Class to signal a Source with a region.

Note

This class serves as a base class to identify all sources with positional information.

class TiledLayout(sources=None, expression=None, tile_axes=None, tile_shape=None, tile_positions=None, positions=None, overlaps=None, alignments=None, position=None, shape=None, dtype=None, order=None, location=None)

Bases: Layout

TiledLayout handles stacks aligned on a tiling grid.

adjust_overlaps(overlaps=None)

Adjusts the positions of the sources given a new estimate of the overlaps.

Arguments

overlapstuple of ints or None

Overlaps of the sources in each grid dimension.

align_on_tiling(overlaps=(50, 50), max_shifts=(-50, 50), clip=None, background=None, processes=None, verbose=False)

Align pairwise images using overlaps along and grid information.

Arguments

layoutTiledLayout

The grid layout of the sources.

overlapsint, tuple of ints or list of tuple of ints

The overlaps along the grid axes.

max_shiftstuple or list of tuple of ints

The maximal shifts along the axes directions.

clipnumber or None

If not None, clip the soruces at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

processesint or ‘serial’

Number of processor to use for parallel processing, if ‘serial’ process in serial.

verbosebool

If True, print progress information.

Returns

layoutLayout class

The updated layout.

alignment_from_tile_positions(tile_position1, tile_position2)

Returns the alignemtn between two tiles if exists..

Arguments

tile_position1,2tuple of ints

The position of the sources in the grid.

Returns

alignmentAlignment class or None

The alignment between the tile positions, None if not found.

alignments_from_tile_position(tile_position)

Returns a list of all alignments that involve a specified tile.

Arguments

tile_positiontuple of ints

The position of the source.

Returns

alignmentslist of Alignment class

The alignments involved in the specified tile position,

center_tile_position()

Returns the most center tile position in this layout.

Returns

tile_centertuple of ints

The tile position of the most central tile.

center_tile_source()

Returns the most central source in this tile layout.

Returns

centertuple of ints

The most central tile.

sort_sources_by_tile_position()

Sorts the sources of this layout by grid position.

source_from_tile_position(tile_position)

Maps the grid position to a source in this layout.

Arguments

tile_positiontuple of ints

The position of the source in the grid.

Returns

sourceSource class or None

The source at the required grid position, None if not found.

source_to_tile_position(source)

Maps the source to a position on the grid in this layout.

Arguments

sourceSource class or int

The souce or id of the source to map to a grid position.

Returns

positionstuple of ints or None

The grid position of the source, None if not found.

property tile_dim

Returns the dimension of the grid.

Returns

g_dimint

The grid dimension.

property tile_positions

Returns the list of the grid positions of the sources.

Returns

tile_positionslist of tuple of ints

The grid positions of the sources.

align_2_sources(src1, src2, max_shifts=10, clip=None, background=None, normalize=False, verbose=False, debug=False)

Align 2 sources using root mean square difference measure.

Arguments

src1, src2array like sources

Sources to align.

max_shiftsint, tuple or list of tuples of ints

The minimum and maximum shifts along the different axes to consider for alignment.

clipnumber or None

If not None, clip the sources at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

normalizebool

Use normalized cross correlation, instead of co-variance, i.e. subtract mean and divide by std.

verbosebool

If True print progress information.

Returns

shiftarray

The additional shift between the first and second source for optimal pairwise alignment.

qualityfloat

Quality measure.

align_2_sources_along_axis(src1, src2, axis=0, overlap=10, max_shifts=10, clip=None, background=None, verbose=False)

Align 2 images along a specified axis.

Arguments

src1, src22d arrays

The images to align.

axisint

The alignment axis.

overlaptuple of int

The minimum and maximum overlap along the alignment axis

max_shiftsint, tuple of int or list of tuple of ints

The minimum and maximum shifts along the different axes. Only the values for the axes orthogonal to the alignment axis are used.

clipnumber or None

If not None, clip the sources at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

verbosebool

If True, print progress information.

Returns

shiftarray

The shift of the second image wrt to the first for optimal pairwise alignment.

qualityfloat

A quality measure of the alignment.

Note

This routine simply translates overlap specifications in one axis direction into max_shifts for use with align_2_sources.

align_2_sources_along_axis_mip(src1, src2, axis=2, depth=10, max_shifts=10, clip=None, background=None, verbose=False, with_mip=False)

Align 2 images orthogonal to a spcified axis using max projection

Arguments

src1, src2: 2d arrays

The sources to align.

axis: int

Axis for max intensity projection (mip).

depthint

The depth to use for the maximum intensity projection along the mip axis.

max_shifts: tuple of int

The minimum and maximum shifts along the axes.

clipnumber or None

If not None, clip the soruces at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

verbosebool

If True, print progress information.

with_mip: bool

If True, also return the maximum projections used to aling the two sources.

Returns

shiftarray

The shift of the second image wrt to the first for optimal pairwise alignment orthogonal to mip axis

qualityfloat

The quality measure of the alignment.

mipstuple of arrays

Optional maximum intensity projections.

align_layout(layout, max_shifts=10, clip=None, background=None, processes=None, verbose=False)

Aligns the sources in a layout.

Arguments

layoutLayout class

The layout of the sources.

max_shiftsint, tuple of ints or list of list of tuple of ints

The maximal shifts of the images with respect to each other along each dimension.

clipnumber or None

If not None, clip the soruces at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

processesint or ‘serial’

Number of processor to use for parallel processing, if ‘serial’ process in serial.

verbosebool

If True, print progress information.

Returns

layoutLayout class

The layout with the new alignments.

align_layout_axis(layout, axis=2, depth=10, max_shifts=10, axis_range=None, clip=None, background=None, processes=None, verbose=False)

Aligns sources in a layout in a single axis direction only.

Arguments

layout: Layout class

The layout in which to align the 3d sources in z-direction.

axisint

The axis along to aling the layout.

depthint or list of ints

The approximate overlaps of the images in the different dimensions to use for mip projection. Only the depth parameter along the relevant axis is used.

max_shiftstuple of ints

The minmal and maximal shift in to consider.

axis_rangetuple of int or None

Use only a sub set of the axis range to speed up processing.

clipnumber or None

If not None, clip the soruces at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

processesint or ‘serial’

Number of processor to use for parallel processing, if ‘serial’ process in serial.

verbosebool

Print progress information.

Returns

layoutLayout

The layout with updated axis-alignments.

Note

To speed up the calculation, a mip projection is used in the direction of the tiling

align_layout_on_tiling(layout, overlaps=10, max_shifts=10, clip=None, background=None, processes=None, verbose=False)

Calculates shifts of the sources on a gird layout that aligns them.

Arguments

layoutTiledLayout

The grid layout of the sources.

overlapstuple of ints

The overlaps along the grid axes.

max_shiftstuple or list of tuple of ints

The maximal shifts along the axes directions.

clipnumber or None

If not None, clip the soruces at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

processesint or ‘serial’

Number of processor to use for parallel processing, if ‘serial’ process in serial.

verbosebool

If True, print progress information.

Returns

layoutTiledLayout class

The updated layout after alignment.

align_layout_rigid_mip(layout, depth=10, max_shifts=10, ranges=None, clip=None, background=None, processes=None, workspace=None, verbose=False)

Aligns sources in a layout in a single axis direction only.

Arguments

layout: Layout class

The layout in which to align the 3d sources in z-direction.

depthint or list of ints

The approximate overlaps of the images in the different dimensions to use for mip projection. Only the depth parameter along the relevant axis is used.

max_shiftstuple of ints

The minmal and maximal shift in to consider.

axis_rangetuple of int or None

Use only a sub set of the axis range to speed up processing.

clipnumber or None

If not None, clip the soruces at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

processesint or ‘serial’ layout.alig

Number of processor to use for parallel processing, if ‘serial’ process in serial.

verbosebool

Print progress information.

Returns

layoutLayout

The layout with updated axis-alignments.

Note

To speed up the calculation, a mip projection is used in the direction of the tiling. The tiling dimension are assumed to be alinged with the first image dimensions.

align_layout_rigid_mips(layout, depth=10, max_shifts=10, ranges=None, clip=None, background=None, processes=None, verbose=False)

Aligns sources in a layout using mip in all directions.

Arguments

layout: Layout class

The layout in which to align the 3d sources in z-direction.

depthint or list of ints

The approximate overlaps of the images in the different dimensions to use for mip projection. Only the depth parameter along the relevant axis is used.

max_shiftstuple of ints

The minmal and maximal shift in to consider.

axis_rangetuple of int or None

Use only a sub set of the axis range to speed up processing.

clipnumber or None

If not None, clip the soruces at this value when calculating the alignment.

backgroundnumber or None

If not None, if the values in the overlap region are less than this number make alignment return -inf quality as there is no signal to use for alignment.

processesint or ‘serial’ layout.alig

Number of processor to use for parallel processing, if ‘serial’ process in serial.

verbosebool

Print progress information.

Returns

layoutLayout

The layout with updated axis-alignments.

Note

To speed up the calculation, a mip projection is used in the direction of the tiling. The tiling dimension are assumed to be alinged with the first image dimensions.

alignments_from_source_positions(alignments)

Update alignment shifts from source positions and shapes

Arguments

alignmentslist of Alignments classes

The alignments pairs of the sources.

Returns

alignmentslist of Alignments classes

The updated alignments.

check_alignments_and_sources(alignments, sources, verbose=False)

Checks consistency of alignments and sources.

connected(alignments, sources=None)

Returns True if the alignments form a single connected component.

Arguments

alignmentslist of Alignment classes

The pairwise alignments.

sourceslist of Source classes or None

Optional list of all sources.

Returns

connectedbool

True if the alignments form a single connected component.

connected_components(alignments, sources=None, min_quality=None, with_sources=False)

Returns the connected components of the alignments

Arguments

alignmentslist of Alignment classes

The pairwise alignments.

sourceslist of Source classes or None

Optional list of all sources.

min_qualityfloat, tuple of floats or None

The mininal quality for alignments to be included in the calculation.

with_sourcesbool

If True, also return the sources in each component, as single sources might not appear in the alignment components.

Returns

componentslist of list of Alignment classes

The connected components of the alignments.

copy_sources_and_alignments(sources, alignments)

Copys the sources and alignments but not the underlying array data.

Arguments

sourceslist of Source classes or None

List of sources.

alignmentslist of Alignment classes

The pairwise alignments.

Returns

sourceslist of Source classes or None

Copied list of sources.

alignmentslist of Alignment classes

Copied list of pairwise alignments.

embedding(sources, shape=None, position=None)

Splits a set of co-axial sources into a minimal set of non-overlaping regions.

Arguments

sourceslist of Source or Region classes

The sources to embed in a full image.

shapetuple of ints or None

Optional fixed shape of the full image, if None use the minimal shape that fits all sources.

positiontuple of ints or None

Optional position form which to start the stitching. Together with shape this can be used to restrict the stitching region. If None, use the minimal position that fits all the contributing sources.

Returns

shapetuple of int

The shape that encapsulates all the regions.

positiontuple of int

The lowest corner of all the regions.

regionslist of Overlap classes.

The regions of different overlaps of the individual sources.

Note

The result can be used to stitch the images.

filter_alignments(alignments, min_quality=-inf)

Filter out alignments that fall below a certain quality level.

Arguments

alignmentslist of Alignments classes

The pairwise alignments between images to optimize globally.

min_qualityfloat

The minimal quality of the alignment.

Returns

alignmentslist of Alignment classes

The filtered alignments.

layout_along_axis_mip(src1, src2, axis=2, depth=10, max_shifts=10, ranges=None, verbose=False)

Layout corresponding to a mip projected alignment

Arguments

Returns

layout_coloring(layout, colors=None, color_ids=None)

load_layout(filename)

Loads a layout class from a file

Arguments

filenamestr

The file to load the layout from.

Returns

layoutLayout class

The loaded layout.

max_intensity_projection(data, axis=0, function=<function max>)

Returns the max intensity projection along a specified axis.

Arguments

dataarray

The data array.

axisint

The axis along which to perform the maximum projection.

Returns

miparray

The maximum intensity projection of the data along axis.

overlap(region1, region2)

Overlap between two regions.

overlay_along_axis_mip(src1, src2, axis=2, depth=10, max_shifts=10, ranges=None, verbose=False, **kwargs)

overlay_layout(layout, colors=None, percentile=98, normalize=True, color_ids=None)

Overlays the sources to check their placement.

Arguments

layoutLayout class

The layout with the sources to overlay.

colorslist of tuple of floats or color names

The optional RGB colors to use.

percentileint

Use this percentile as upper cutoff in the resulting image to enhance contrast.

normalizebool

If True normalize image to floats between 0 and 1.

Returns

imagearray

A color image.

overlay_sources(sources, colors=None, percentile=98, normalize=True)

Overlays the sources to check thier placement.

Arguments

layoutLayout class

The layout with the sources to overlay.

colorslist of tuple of floats or color names

The optional RGB colors to use.

percentileint

Use this percentile as upper cutoff in the resulting image to enhance contrast.

normalizebool

If True normalize image to floats between 0 and 1.

Returns

imagearray

A color image.

place_layout(layout, method='optimization', min_quality=None, lower_to_origin=False, verbose=False)

Place the sources in a layout in a consistent way.

Arguments

layoutLayout class

The layout in which the Sources will be placed in a consistent way.

method‘optimization’ or ‘tree’

The method to use to place the sources.

min_qualityfloat

The minimal quality of the alignments to include in the placement process.

lower_to_originbool

If True, the lower corner of the aligned sources is set to zero.

Returns

layoutLayout class

The layout with the optimized positions of the sources.

place_layout_axis(layout, axis=2, method='optimization', min_quality=None, lower_to_origin=False, verbose=False)

Places the sources in a layout along a single axis only.

Arguments

layout: Layout class

The layout of the stacks.

method‘optimization’ or ‘tree’

The method to use to place the sources.

min_qualityfloat

The minimal quality of the alignment.

lower_to_originbool

If True the lower corner of the aligned images is set to zero.

Returns

layoutLayout

The layout with updated z-alignments.

plot_alignments(alignments, sources=None, axes=[0, 1], annotate=True, min_quality=-inf, cmap=<matplotlib.colors.LinearSegmentedColormap object>)

Plots the alignments with their quality

plot_along_axis_mip(src1, src2, axis=2, depth=10, max_shifts=10, ranges=None, verbose=False, **kwargs)

plot_layout(layout, colors=None, percentile=98, normalize=True, color_ids=None)

Overlays and plots sources in a layout to check alignment.

Arguments

layout: Layout class

The layout to use for plotting.

colorslist of colors or None

The optional RGB colors to use.

percentileint

Use this percentile as upper cutoff in the resulting image to enhance contrast.

normalizebool

If True normalize image to floats between 0 and 1.

Returns

imagearray

A color image of the overlayed sources.

plot_regions(regions, sources=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, annotate=True, axes=[0, 1])

Overlays and plots regions to check the alignment.

Arguments

regionslist of Region classes.

The regions to plot.

cmapcolormap

The color map to use to color the regions.

annotatebool

Use annotaton or not.

plot_sources(sources, colors=None, percentile=98, normalize=True)

Overlays and plots sources in a layout to check alignment.

Arguments

layout: Layout class

The layout to use for plotting.

colorslist of colors or None

The optional RGB colors to use.

percentileint

Use this percentile as upper cutoff in the resulting image to enhance contrast.

normalizebool

If True normalize image to floats between 0 and 1.

Returns

imagearray

A color image of the overlayed sources.

positions_from_optimization(alignments, sources=None, min_quality=None, fixed_source=None, lower_to_origin=False)

Use least squares optimization to find globally optimal source positions from pairwise alignments.

Arguments

alignmentslist of Alignments classes

The pairwise alignments between images to optimize globally.

sourceslist of Source classes or None

The sources to optimze the positions for, if None determine from the alignments.

min_qualityfloat

The minimal quality of the alignment.

fixed_sourceSource class, int or None

Optional source to kept fixed. If None the first source is kept fixed.

lower_to_originbool

If True, the lower corner of the aligned images is set to zero.

Returns

sourceslist of Source classes

The sources with the optimized positions.

Note

The error function is sum (x_i + s_ij - x_j)^2 with x_i the image positions and s_ij the pairwise shifts.

positions_from_tree(alignments, sources=None, min_quality=None, fixed_source=None, lower_to_origin=False)

Update source positions from alignments.

Arguments

alignmentslist of Alignments classes

The alignments pairs of the sources.

sourceslist of Source classes or None

Optional sources to update the positions for, if None extracted from alignment classes.

min_qualityfloat

The minimal quality of the alignment.

fixed_sourceSource class, int or None

Optional source to kept fixed. If None the first source is placed at the origin.

lower_to_originbool

If True the lower corner of the aligned images is set to zero.

Returns

positionslist of tuple of ints

The source positions.

Note

The result will be a single consistent solution based on a minimal paths between the first and the other sources of the layout.

save_layout(filename, layout)

Saves a layout class to a file.

Arguments

filenamestr

The file to save the layout too.

layoutLayout class

The layout to save.

Returns

file_namestr

The file name in which the layout was saved.

slice_layout_along_axis(layout, coordinate, axis=2)

Slice a layout at a coordinate along an axis.

Arguments

layoutLayout class

The layout to take the slice through.

coordinateint

The coordinate of the slice along the slice axis in the original layout.

axisint

The axis used to slice the layout.

Note

The sources of the layout will be sliced accordingly. The sources position along the axis is taken into account and sources not in the slice are droped. Thus, ensure the position along the slice axis is aligned, e.g. by using aling_layout_along_axis().

source_index(sources, source)

The index of a source in the list of sources.

Arguments

sourceslist of source classes

The list of sources to search in.

sourceSource class

The source to search for.

Returns

indexint or None

Position of the source in the sources list, None if not found.

sources_from_alignments(alignments)

Returns a unique list of sources from the given alignments.

Arguments

alignmentslist of Alignment classes

The pairwise alignments.

Returns

sourceslist of Source classes

A unique list of the sources.

stitch_by_function(layout, sink=None, function=<function max>)

Stitch sources according to shifts applying a specific function in the overlapping regions.

Arguments

layoutLayout class

The layout to use for the sources.

sinkarray like or None

The sink to write the result to.

functionfunction

The function to apply in overlapping regions, e.g. np.max or np.mean.

Returns

stitchedarray

The stitched array.

stitch_by_function_with_weights(layout, sink=None, function=<function sum>, weight_function=<function stitch_weights>)

Stitch sources applying a specific weighting function in the overlapping regions.

Arguments

layoutLayout class

The layour of the sources.

sinkarray like or None

The sink to write the result to.

functionfunction

The function to apply in overlapping regions, e.g. np.sum or np.mean.

weight_functionfunction

A function that returns an array of pixel weights given the source shape.

Returns

stitchedarray

The stitched array.

stitch_by_interpolation(layout, sink=None)

Stitch sources according to shifts applying linear interpolation in the overlap regions.

Arguments

layoutLayout class

The layout of the sources.

sinkarray like or None

The sink to write the result to.

Returns

stitchedarray

The stitched array.

stitch_by_interpolation_adjust_max(layout, sink=None)

Stitch sources according to shifts applying linear interpolation in the overlap regions.

Arguments

layoutLayout class

The layout of the sources.

sinkarray like or None

The sink to write the result to.

Returns

stitchedarray

The stitched array.

stitch_by_max(layout, sink=None)

Stitch sources according to shifts applying max function in the overlap regions.

Arguments

layoutLayout class

The layout of the sources.

sinkarray like or None

The sink to write the result to.

Returns

stitchedarray

The stitched array.

stitch_by_mean(layout, sink=None)

Stitch sources according to shifts applying mean function in the overlap regions.

Arguments

layoutLayout class

The layout of the sources.

sinkarray like or None

The sink to write the result to.

Returns

stitchedarray

The stitched array.

stitch_by_min(layout, sink=None)

Stitch sources according to shifts applying min function in the overlap regions.

Arguments

layoutLayout class

The layout of the sources.

sinkarray like or None

The sink to write the result to.

Returns

stitchedarray

The stitched array.

stitch_layout(layout, sink=None, method='interpolation', verbose=False)

Stitch a layout according to its current alignment.

Arguments

layoutLayout class

The layout of the sources.

sinkarray like or None

The sink to write the result to.

methodstr

The method to use for the stitching: ‘interpolation’, ‘max’, ‘min’, ‘mean’

verbosebool

If True, print progress information.

Returns

stitchedarray

The stitched array.

stitch_weights(shape)

Returns the weights of a source of a given shape to use in stitching routines.

Arguments

shapetuple of ints

The shape of the source.

Returns

weightsarray

The weigthsfor the pixels of the source.