Module imagingbook.common
Package imagingbook.common.image

Class PixelPack

java.lang.Object
imagingbook.common.image.PixelPack
Direct Known Subclasses:
ColorPack
public class PixelPack extends Object

This class defines a generic data container for scalar and vector-valued images, using float-values throughout. Its primary use is in the GenericFilter framework. A PixelPack may represent images with an arbitrary number of components. Scalar images (such as ByteProcessor, ShortProcessor and FloatProcessor) have 1 component, color images (such as ColorProcessor) typically have 3 components. Conversion methods to and from ImageJ's processor classes are provided, with optional scaling of pixel component values.

Internally, pixel data are stored as 1-dimensional float arrays, one array for each component. Method getData() may be used to access the internal data directly. Individual components may be extracted as a PixelPack.PixelSlice using method getSlice(int).

Methods getPix(int, int) and setPix(int, int, float...) are provided to read and write individual pixels, which are ALWAYS of type float[] (even if the underlying image is scalar-valued). Pixel values returned for positions outside the image boundaries depend on the OutOfBoundsStrategy specified by the constructor (e.g., PixelPack(ImageProcessor, double, OutOfBoundsStrategy)).

Here is a simple usage example:

 ColorProcessor ip1 = ... ;     // some color image
 PixelPack pack = new PixelPack(ip1);
 // process pack:
 float[] val = pack.getPix(0, 0);
 pack.setPix(0, 0, 128, 19, 255);
 ...
 ColorProcessor ip2 = pack.toColorProcessor();

A related concept for providing unified access to images is ImageAccessor. In contrast to PixelPack, ImageAccessor does not duplicate any data but reads and writes the original ImageProcessor pixel data directly.

Version:
2022/09/03
See Also:

  • Field Details

  • Constructor Details

    • PixelPack

      public PixelPack(int width, int height, int depth, OutOfBoundsStrategy obs)
      Constructor, creates a blank (zero-valued) pack of pixel data.
      Parameters:
      width - the image width
      height - the image height
      depth - the number of channels (slices)
      obs - strategy to be used when reading from out-of-bounds coordinates (pass null for default)

    • PixelPack

      public PixelPack(ImageProcessor ip)
      Constructor, creates a pack of pixel data from the given ImageProcessor object. Does not scale pixel values and uses DefaultOutOfBoundsStrategy as the out-of-bounds strategy (see OutOfBoundsStrategy).
      Parameters:
      ip - the source image

    • PixelPack

      public PixelPack(ImageProcessor ip, double scale, OutOfBoundsStrategy obs)
      Constructor, reates a pack of pixel data from the given ImageProcessor object, using the specified out-of-bounds strategy.
      Parameters:
      ip - the source image
      scale - scale factor applied to pixel components
      obs - strategy to be used when reading from out-of-bounds coordinates (pass null for default)

    • PixelPack

      public PixelPack(PixelPack orig)
      Constructor, creates a new PixelPack with the same dimension as the original without copying the contained pixel data (initialized to zero).
      Parameters:
      orig - the original PixelPack

    • PixelPack

      public PixelPack(PixelPack orig, boolean copyData)
      Constructor, creates a new PixelPack with the same dimension as the original. Optionally the original pixel data are copied, otherwise they are initialized to zero values.
      Parameters:
      orig - the original PixelPack
      copyData - set true to copy pixel data

  • Method Details

    • getVec

      @Deprecated public float[] getVec(int u, int v, float[] vals)
      Deprecated.

    • getVec

      @Deprecated public float[] getVec(int u, int v)
      Deprecated.

    • setVec

      @Deprecated public void setVec(int u, int v, float... vals)
      Deprecated.

    • getPix

      public void getPix(int u, int v, float[] vals)
      Reads the pixel data at the specified image position. The supplied array is filled. The length of this array must match corresponds the number of slices in this pixel pack. The values returned for out-of-bounds positions depend on this pixel-pack's out-of-bounds strategy.
      Parameters:
      u - the x-position
      v - the y-position
      vals - a suitable array of pixel data

    • getPix

      public float[] getPix(int u, int v)
      Returns the pixel data at the specified position as a float[]. The values returned for out-of-bounds positions depend on this pixel-pack's out-of-bounds strategy.
      Parameters:
      u - the x-position
      v - the y-position
      Returns:
      the array of pixel component values

    • getPix

      public void getPix(int idx, float[] vals)
      Reads the pixel data at the specified 1D index. The supplied array is filled. The length of this array must match corresponds the number of slices in this pixel pack. The index is not checked, the corresponding pixel must always be inside the image bounds, otherwise an exception will be thrown.
      Parameters:
      idx - a valid 1D pixel index (in row-major order)
      vals - a suitable array of pixel data

    • getPix

      public float[] getPix(int idx)
      Returns the pixel data at the specified position as a float[]. The index is not checked, the corresponding pixel must always be inside the image bounds, otherwise an exception will be thrown.
      Parameters:
      idx - a valid 1D pixel index (in row-major order)
      Returns:
      the array of pixel component values

    • setPix

      public void setPix(int u, int v, float... vals)
      Sets the pixel data at the specified pixel position. The length of the value array corresponds to the number of slices (components) in this pixel pack.
      Parameters:
      u - the x-position
      v - the y-position
      vals - the pixel's component values (may also be a float[])

    • setPix

      public void setPix(int idx, float... vals)

    • copyTo

      public void copyTo(PixelPack other)
      Copies the contents of one pixel pack to another. The involved pixel packs must have the same dimensions.
      Parameters:
      other - another pixel pack

    • isCompatibleTo

      public boolean isCompatibleTo(PixelPack other)
      Checks is this pixel pack has the same dimensions as another pixel pack, i.e., can be copied to it.
      Parameters:
      other - the other pixel pack
      Returns:
      true if both have the same dimensions

    • isCompatibleTo

      public boolean isCompatibleTo(ImageProcessor ip)
      Checks is this pixel pack has the same dimensions as the specified ImageProcessor instance, i.e., can be copied to it.
      Parameters:
      ip - the image processor instance
      Returns:
      true if compatible

    • getSlice

      public PixelPack.PixelSlice getSlice(int k) throws IllegalArgumentException
      Returns the kth PixelPack.PixelSlice. An exception is thrown if the specified slice does not exist.
      Parameters:
      k - the slice index (0,...,K-1)
      Returns:
      the kth PixelPack.PixelSlice
      Throws:
      IllegalArgumentException - if slice with the given index does not exist

    • getEmptySlice

      public PixelPack.PixelSlice getEmptySlice()
      Creates and returns a new PixelPack.PixelSlice with the same dimensions and out-of-bounds strategy as this PixelPack.
      Returns:
      a new pixel slice

    • getSlices

      public PixelPack.PixelSlice[] getSlices()
      Returns an array of PixelPack.PixelSlice instances for this PixelPack. All pixel data are shared.
      Returns:
      an array of PixelPack.PixelSlice

    • getFloatProcessor

      public FloatProcessor getFloatProcessor(int k)
      Returns the FloatProcessor for the kth pixel slice. An exception is thrown if the specified slice does not exist.
      Parameters:
      k - the slice index (0,...,K-1)
      Returns:
      the kth FloatProcessor

    • getFloatProcessors

      public FloatProcessor[] getFloatProcessors()
      Returns an array of FloatProcessor instances for this PixelPack. All pixel data are shared.
      Returns:
      an array of FloatProcessor

    • getData

      public float[][] getData()
      Returns a reference to this PixelPack's internal data array, which is always two-dimensional: dimension 1 is the slice (component) index, dimension 2 is the pixel index (each slice is a 1D array).
      Returns:
      the pixel pack's data array

    • getWidth

      public int getWidth()
      Returns the width of the associated image.
      Returns:
      the image width

    • getHeight

      public int getHeight()
      Returns the height of the associated image.
      Returns:
      the image height

    • getDepth

      public int getDepth()
      Returns the depth (number of slices) of the associated image.
      Returns:
      the image depth

    • getOutOfBoundsStrategy

      public OutOfBoundsStrategy getOutOfBoundsStrategy()
      Returns the out-of-bounds strategy.
      Returns:
      the out-of-bounds strategy

    • zero

      public void zero()
      Sets all values of this pixel pack to zero.

    • get3x3Neighborhood

      public float[][][] get3x3Neighborhood(int uc, int vc, float[][][] nh)
      Returns the pixel values in the 3x3 neighborhood around the specified position. The returned float-array has the structure [x][y][k], with x,y = 0,...,2 and k is the slice index.
      Parameters:
      uc - the center x-position
      vc - the center x-position
      nh - a float array to be filled in (or null)
      Returns:
      the neighborhood array

    • copyFromImageProcessor

      public void copyFromImageProcessor(ImageProcessor ip)
      Copies the contents of an image processor to an existing pixel pack, which must be compatible w.r.t. size and depth. Does not scale pixel values.
      Parameters:
      ip - the image processor to be copied

    • copyFromImageProcessor

      public void copyFromImageProcessor(ImageProcessor ip, double scale)
      Copies the contents of an image processor to an existing pixel pack, which must be compatible w.r.t. size and depth. Applies the specified scale factor to the pixel component values.
      Parameters:
      ip - the image processor to be copied
      scale - scale factor applied to pixel component values

    • toByteProcessor

      public ByteProcessor toByteProcessor()
      Converts this PixelPack to a new ByteProcessor instance. An exception is thrown if the depth of the pack is not equal 1. Pixel values are rounded, no scale factor is applied.
      Returns:
      a new ByteProcessor instance

    • toByteProcessor

      public ByteProcessor toByteProcessor(double scale)
      Converts this PixelPack to a new ByteProcessor instance. An exception is thrown if the depth of the pack is not equal 1. Applies the specified scale factor to pixel values.
      Parameters:
      scale - scale factor applied to pixel values (before rounding)
      Returns:
      a new ByteProcessor instance

    • toShortProcessor

      public ShortProcessor toShortProcessor()
      Converts this PixelPack to a new ShortProcessor instance. An exception is thrown if the depth of the pack is not equal 1. Pixel values are rounded, no scale factor is applied.
      Returns:
      a new ShortProcessor instance

    • toShortProcessor

      public ShortProcessor toShortProcessor(double scale)
      Converts this PixelPack to a new ShortProcessor instance. An exception is thrown if the depth of the pack is not equal 1. Applies the specified scale factor to pixel values.
      Parameters:
      scale - scale factor applied to pixel values (before rounding)
      Returns:
      a new ShortProcessor instance

    • toFloatProcessor

      public FloatProcessor toFloatProcessor()
      Converts this PixelPack to a new FloatProcessor instance. An exception is thrown if the depth of the pack is not equal 1. No scale factor is applied to pixel values.
      Returns:
      a new FloatProcessor instance

    • toFloatProcessor

      public FloatProcessor toFloatProcessor(double scale)
      Converts this PixelPack to a new FloatProcessor instance. An exception is thrown if the depth of the pack is not equal 1.
      Parameters:
      scale - scale factor applied to pixel values
      Returns:
      a new FloatProcessor instance

    • toColorProcessor

      public ColorProcessor toColorProcessor()
      Converts this PixelPack to a new ColorProcessor instance. An exception is thrown if the depth of the pack is not equal 3. Component values are rounded, no scale factor is applied.
      Returns:
      a new ColorProcessor instance

    • toColorProcessor

      public ColorProcessor toColorProcessor(double scale)
      Converts this PixelPack to a new ColorProcessor instance. An exception is thrown if the depth of the pack is not equal 3.
      Parameters:
      scale - scale factor applied to component values (before rounding)
      Returns:
      a new ColorProcessor instance

    • toImageStack

      public ImageStack toImageStack()
      Converts this PixelPack to a new ImageStack with the same number of slices (see getDepth()). The stack images are of type FloatProcessor. The resulting ImageStack does not share any pixel data with this PixelPack.
      Returns:
      a new ImageStack instance

    • copyToImageProcessor

      public void copyToImageProcessor(ImageProcessor ip)
      Copies the contents of a pixel pack to an existing image processor. They must be compatible w.r.t. size and depth. Component values are rounded if necessary, no scale factor is applied.
      Parameters:
      ip - the receiving image processor

    • copyToImageProcessor

      public void copyToImageProcessor(ImageProcessor ip, double scale)
      Copies the contents of a pixel pack to an existing image processor. They must be compatible w.r.t. size and depth. Component values are rounded if necessary, after the specified scale factor is applied.
      Parameters:
      ip - the receiving image processor
      scale - scale factor applied to pixel values