Image Registration (nornir_imageregistration)

alignment_record

class nornir_imageregistration.alignment_record.AlignmentRecord(peak, weight, angle=0.0, flipped_ud=False, scale=1.0)

Records basic registration information as an angle and offset between a fixed and moving image If the offset is zero the center of both images occupy the same point. The offset determines the translation of the moving image over the fixed image. There is no support for scale, and there should not be unless added as another variable to the alignment record

Parameters

  • peak (array) – Translation vector for moving image

  • weight (float) – The strength of the alignment

  • angle (float) – Angle to rotate moving image in degrees

core

scipy image arrays are indexed [y,x]

nornir_imageregistration.core.ConstrainedRange(start, count, maxVal, minVal=0)

Returns a range that falls within min/max limits.

nornir_imageregistration.core.ConvertImagesInDict(ImagesToConvertDict, Flip=False, Flop=False, InputBpp=None, OutputBpp=None, Invert=False, bDeleteOriginal=False, RightLeftShift=None, AndValue=None, MinMax=None, Gamma=None)

The key and value in the dictionary have the full path of an image to convert. MinMax is a tuple [Min,Max] passed to the -level parameter if it is not None RightLeftShift is a tuple containing a right then left then return to center shift which should be done to remove useless bits from the data I do not use an and because I do not calculate ImageMagick’s quantum size yet. Every image must share the same colorspace

Returns

True if images were converted

Return type

bool

nornir_imageregistration.core.CropImage(imageparam, Xo, Yo, Width, Height, cval=None)

Crop the image at the passed bounds and returns the cropped ndarray. If the requested area is outside the bounds of the array then the correct region is returned with a background color set

Parameters

  • imageparam (ndarray) – An ndarray image to crop. A string containing a path to an image is also acceptable.e

  • Xo (int) – X origin for crop

  • Yo (int) – Y origin for crop

  • Width (int) – New width of image

  • Height (int) – New height of image

  • cval (int) – default value for regions outside the original image boundaries. Defaults to 0. Use ‘random’ to fill with random noise matching images statistical profile

Returns

Cropped image

Return type

ndarray

nornir_imageregistration.core.DimensionWithOverlap(val, overlap=1.0)
Parameters

  • val (float) – Original dimension

  • overlap (float) – Amount of overlap possible between images, from 0 to 1

Returns

Required dimension size to unambiguously determine the offset in an fft image

nornir_imageregistration.core.ExtractROI(image, center, area)

Returns an ROI around a center point with the area, if the area passes a boundary the ROI maintains the same area, but is shifted so the entire area remains in the image. USES NUMPY (Y,X) INDEXING

nornir_imageregistration.core.FFTPhaseCorrelation(FFTFixed, FFTMoving, delete_input=False)

Returns the phase shift correlation of the FFT’s of two images.

Dimensions of Fixed and Moving images must match

Parameters

  • FixedImage (ndarray) – grayscale image

  • MovingImage (ndarray) – grayscale image

Returns

Correlation image of the FFT’s. Light pixels indicate the phase is well aligned at that offset.

Return type

ndimage

nornir_imageregistration.core.FindOffset(FixedImage, MovingImage, MinOverlap=0.0, MaxOverlap=1.0, FFT_Required=True, FixedImageShape=None, MovingImageShape=None)

return an alignment record describing how the images overlap. The alignment record indicates how much the moving image must be rotated and translated to align perfectly with the FixedImage.

If adjusting control points the peak can be added to the fixed image’s control point, or subtracted from the warped image’s control point (accounting for any transform used to create the warped image) to align the images.

Parameters

  • FixedImage (ndarray) – Target space we are registering into

  • MovingImage (ndarray) – Source space we are coming from

  • MinOverlap (float) – The minimum amount of overlap by area the registration must have

  • MaxOverlap (float) – The maximum amount of overlap by area the registration must have

  • FFT_Required (bool) – True by default, if False the input images are in FFT space already

  • FixedImageShape (tuple) – Defaults to None, if specified it contains the size of the fixed image before padding. Used to calculate mask for valid overlap values.

  • MovingImageShape (tuple) – Defaults to None, if specified it contains the size of the moving image before padding. Used to calculate mask for valid overlap values.

nornir_imageregistration.core.FindPeak(image, OverlapMask=None, Cutoff=None)

Find the offset of the strongest response in a phase correlation image

Parameters

  • image (ndimage) – grayscale image

  • Cutoff (float) – Percentile used to threshold image. Values below the percentile are ignored

  • OverlapMask (ndimage) – Mask describing which pixels are eligible

Returns

scaled_offset of peak from image center and sum of pixels values at peak

Return type

(tuple, float)

nornir_imageregistration.core.ForceGrayscale(image)
Param

ndarray with 3 dimensions

Returns

grayscale data

Return type

ndarray with 2 dimensions

nornir_imageregistration.core.GenRandomData(height, width, mean, standardDev, min_val, max_val)

Generate random data of shape with the specified mean and standard deviation

nornir_imageregistration.core.GetImageSize(image_param)
Parameters

str (image_param) – Either a path to an image file or an ndarray

Returns

Image (height, width)

Return type

tuple

nornir_imageregistration.core.ImageIntensityAtPercent(image, Percent=0.995)

Returns the intensity of the Cutoff% most intense pixel in the image

nornir_imageregistration.core.ImagePhaseCorrelation(FixedImage, MovingImage)

Returns the phase shift correlation of the FFT’s of two images.

Dimensions of Fixed and Moving images must match

Parameters

  • FixedImage (ndarray) – grayscale image

  • MovingImage (ndarray) – grayscale image

Returns

Correlation image of the FFT’s. Light pixels indicate the phase is well aligned at that offset.

Return type

ndimage

nornir_imageregistration.core.ImageToTiles(source_image, tile_size, grid_shape=None, cval=0)
Parameters

  • source_image (ndarray) – Image to cut into tiles

  • tile_size (array) – Shape of each tile

  • grid_shape (array) – Dimensions of grid, if None the grid is large enough to reproduce the source_image with zero padding if needed

  • cval (object) – Fill value for images that are padded. Default is zero. Use ‘random’ to generate random noise

Returns

Dictionary of images indexed by tuples

nornir_imageregistration.core.ImageToTilesGenerator(source_image, tile_size, grid_shape=None, coord_offset=None, cval=0)

An iterator generating all tiles for an image :param array tile_size: Shape of each tile :param array grid_shape: Dimensions of grid, if None the grid is large enough to reproduce the source_image with zero padding if needed :param tuple coord_offset: Add this amount to coordinates returned by this function, used if the image passed is part of a larger image :param object cval: Fill value for images that are padded. Default is zero. Use ‘random’ to generate random noise :return: (iCol,iRow, tile_image)

nornir_imageregistration.core.LoadImage(ImageFullPath, ImageMaskFullPath=None, MaxDimension=None, dtype=None)

Loads an image converts to greyscale, masks it, and removes extrema pixels.

Parameters

  • ImageFullPath (str) – Path to image

  • ImageMaskFullPath (str) – Path to mask, dimension should match input image

  • MaxDimension – Limit the largest dimension of the returned image to this size. Downsample if necessary.

Returns

Loaded image. Masked areas and extrema pixel values are replaced with gaussian noise matching the median and std. dev. of the unmasked image.

Return type

ndimage

nornir_imageregistration.core.NearestPowerOfTwoWithOverlap(val, overlap=1.0)
Returns

Same as DimensionWithOverlap, but output dimension is increased to the next power of two for faster FFT operations

nornir_imageregistration.core.NormalizeImage(image)

Adjusts the image to have a range of 0 to 1.0

nornir_imageregistration.core.OneBit_img_from_bool_array(data)

Covers for pillow bug with bit images https://stackoverflow.com/questions/50134468/convert-boolean-numpy-array-to-pillow-image

nornir_imageregistration.core.PadImageForPhaseCorrelation(image, MinOverlap=0.05, ImageMedian=None, ImageStdDev=None, NewWidth=None, NewHeight=None, PowerOfTwo=True)

Prepares an image for use with the phase correlation operation. Padded areas are filled with noise matching the histogram of the original image. Optionally the min/max pixels can also replaced be replaced with noise using FillExtremaWithNoise

Parameters

  • image (ndarray) – Input image

  • MinOverlap (float) – Minimum overlap allowed between the input image and images it will be registered to

  • ImageMean (float) – Median value of noise, calculated or pulled from cache if none

  • ImageStdDev (float) – Standard deviation of noise, calculated or pulled from cache if none

  • NewWidth (int) – Pad input image to this dimension if not none

  • NewHeight (int) – Pad input image to this dimension if not none

  • PowerOfTwo (bool) – Pad the image to a power of two if true

Returns

An image with the input image centered surrounded by noise

Return type

ndimage

nornir_imageregistration.core.RandomNoiseMask(image, Mask, ImageMedian=None, ImageStdDev=None, Copy=False)

Fill the masked area with random noise with gaussian distribution about the image mean and with standard deviation matching the image’s standard deviation

Parameters

  • image (ndimage) – Input image

  • mask (ndimage) – Mask, zeros are replaced with noise. Ones pull values from input image

  • ImageMedian (float) – Mean of noise distribution, calculated from image if none

  • ImageStdDev (float) – Standard deviation of noise distribution, calculated from image if none

  • Copy (bool) – Returns a copy of input image if true, otherwise write noise to the input image

Return type

ndimage

nornir_imageregistration.core.ReplaceImageExtramaWithNoise(image, ImageMedian=None, ImageStdDev=None)

Replaced the min/max values in the image with random noise. This is useful when aligning images composed mostly of dark or bright regions

nornir_imageregistration.core.ResizeImage(image, scalar)

Change image size by scalar

nornir_imageregistration.core.SafeROIRange(start, count, maxVal, minVal=0)

Returns a range cropped within min and max values, but always attempts to have count entries in the ROI. If minVal or maxVal would crop the list then start is shifted to ensure the resulting value has the correct number of entries. :param int start: Starting value :param int count: Number of items in the list, incremented by 1, to return. :param int maxVal: Maximum value allowed to be returned. Output list will be cropped if it equals or exceeds this value. :param int minVal: Minimum value allowed to be returned. Output list will be cropped below this value. :return: [start start+1, start+2, …, start+count]

nornir_imageregistration.core.SaveImage(ImageFullPath, image, bpp=None, **kwargs)

Saves the image as greyscale with no contrast-stretching :param str ImageFullPath: The filename to save :param ndarray image: The image data to save :param int bpp: The bit depth to save, if the image data bpp is higher than this value it will be reduced. Otherwise only the bpp required to preserve the image data will be used. (8-bit data will not be upsampled to 16-bit)

nornir_imageregistration.core.SaveImage_JPeg2000(ImageFullPath, image, tile_dim=None)

Saves the image as greyscale with no contrast-stretching

nornir_imageregistration.core.ScalarForMaxDimension(max_dim, shapes)

Returns the scalar value to use so the largest dimensions in a list of shapes has the maximum value

nornir_imageregistration.core.Shrink(InFile, OutFile, Scalar, **kwargs)

Shrinks the passed image file. If Pool is not None the task is returned. kwargs are passed on to Pillow’s image save function :param str InFile: Path to input file :param str OutFile: Path to output file :param float ShrinkFactor: Multiplier for image dimensions

nornir_imageregistration.core.TileGridShape(source_image_shape, tile_size)

Given an image and tile size, return the dimensions of the grid

nornir_imageregistration.core.array_distance(array)

Convert an Mx2 array into a Mx1 array of euclidean distances

nornir_imageregistration.core.index_with_array(image, indicies)

Returns values from image at the coordinates :param ndarray image: Image to index into :param ndarray indicies: nx2 array of pixel coordinates

class nornir_imageregistration.core.memmap_metadata(path, shape, dtype, mode=None)

meta-data for a memmap array

nornir_imageregistration.core.npArrayToReadOnlySharedArray(npArray)

Returns a shared memory array for a numpy array. Used to reduce memory footprint when passing parameters to multiprocess pools

nornir_imageregistration.core.ravel_index(idx, shp)

Convert a nx2 numpy array of coordinates into array indicies

The arrays we expect are in this shape [[X1,Y1],

[X2,Y2], [XN,YN]]

nornir_imageregistration.core.uint16_img_from_float_array(image)

Covers for pillow bug with bit images https://github.com/python-pillow/Pillow/issues/2970

nornir_imageregistration.core.uint16_img_from_uint16_array(data)

Covers for pillow bug with bit images https://github.com/python-pillow/Pillow/issues/2970

assemble

Created on Apr 22, 2013

nornir_imageregistration.assemble.DestinationROI_to_SourceROI(transform, botleft, area, extrapolate=False)

Apply a transform to a region of interest within an image. Center and area are in fixed space

Parameters

  • transform (transform) – The transform used to map points between fixed and mapped space

  • botleft (1x2_array) – The (Y,X) coordinates of the bottom left corner

  • area (1x2_array) – The (Height, Width) of the region of interest

  • exrapolate (bool) – If true map points that fall outside the bounding box of the transform

Returns

Tuple of arrays. First array is fixed space coordinates. Second array is warped space coordinates.

Return type

tuple(Nx2 array,Nx2 array)

nornir_imageregistration.assemble.ExtractRegion(image, botleft=None, area=None, cval=0)

Extract a region from an image

Parameters

  • image (ndarray) – Source image

  • botleft (1x2_array) – The (Y,X) coordinates of the bottom left corner

  • area (1x2_array) – The (Height, Width) of the region of interest

Returns

Image of requested region

Return type

ndarray

nornir_imageregistration.assemble.FixedImageToWarpedSpace(transform, WarpedImageArea, DataToTransform, botleft=None, area=None, cval=None, extrapolate=False)

Warps every image in the DataToTransform list using the provided transform. :Param transform: transform to pass warped space coordinates through to obtain fixed space coordinates :Param FixedImageArea: Size of fixed space region to map pixels into :Param DataToTransform: Images to read pixel values from while creating fixed space images. A list of images can be passed to map multiple images using the same coordinates. A list may contain filename strings or numpy.ndarrays :Param botleft: Origin of region to map :Param area: Expected dimensions of output :Param cval: Value to place in unmappable regions, defaults to zero. :param bool exrapolate: If true map points that fall outside the bounding box of the transform

nornir_imageregistration.assemble.ParameterToStosTransform(transformData)
Parameters

transformData (object) – Either a full path to a .stos file, a stosfile, or a transform object

Returns

A transform

nornir_imageregistration.assemble.SourceROI_to_DestinationROI(transform, botleft, area, extrapolate=False)

Apply an inverse transform to a region of interest within an image. Center and area are in fixed space

Parameters

  • transform (transform) – The transform used to map points between fixed and mapped space

  • botleft (1x2_array) – The (Y,X) coordinates of the bottom left corner

  • area (1x2_array) – The (Height, Width) of the region of interest

  • exrapolate (bool) – If true map points that fall outside the bounding box of the transform

Returns

Tuple of arrays. First array is fixed space coordinates. Second array is warped space coordinates.

Return type

tuple(Nx2 array,Nx2 array)

nornir_imageregistration.assemble.TransformImage(transform, fixedImageShape, warpedImage, CropUndefined)

Cut image into tiles, assemble small chunks :param transform transform: Transform to apply to point to map from warped image to fixed space :param ndarray fixedImageShape: Width and Height of the image to create :param ndarray warpedImage: Image to transform to fixed space :param bool CropUndefined: If true exclude areas outside the convex hull of the transform, if it exists :return: An ndimage array of the transformed image

nornir_imageregistration.assemble.TransformStos(transformData, OutputFilename=None, fixedImage=None, warpedImage=None, scalar=1.0, CropUndefined=False)

Assembles an image based on the passed transform. :param str fixedImage: Image describing the size we want the warped image to fill, either a string or ndarray :param str warpedImage: Image we will warp into fixed space, either a string or ndarray :param float scalar: Amount to scale the transform before passing the image through :param bool CropUndefined: If true exclude areas outside the convex hull of the transform, if it exists :param bool Dicreet: True causes points outside the defined transform region to be clipped instead of interpolated :return: transformed image

nornir_imageregistration.assemble.WarpedImageToFixedSpace(transform, FixedImageArea, DataToTransform, botleft=None, area=None, cval=None, extrapolate=False)

Warps every image in the DataToTransform list using the provided transform. :Param transform: transform to pass warped space coordinates through to obtain fixed space coordinates :Param FixedImageArea: Size of fixed space region to map pixels into :Param DataToTransform: Images to read pixel values from while creating fixed space images. A list of images can be passed to map multiple images using the same coordinates. A list may contain filename strings or numpy.ndarrays :Param botleft: Origin of region to map :Param area: Expected dimensions of output :Param cval: Value to place in unmappable regions, defaults to zero. :param bool extrapolate: If true map points that fall outside the bounding box of the transform

assemble_tiles

Created on Oct 28, 2013

Deals with assembling images composed of mosaics or dividing images into tiles