Interface Image


public interface Image
A 2-dimensional pixel plane with associated multi-dimensional coordinates and metadata.

Image objects are immutable (cannot be modified once created). This makes it easier to pass around images between multple threads or data structures, since you don't need to worry about another process modifying it.

In order to "modify" an Image, you will need to create a "copy", but creating a copy is very efficient because the actual pixels and metadata (which don't change) can be shared and do not need to be copied.

To create an Image, (TODO document).

To access the pixel data of an Image, (TODO document).

  • Method Summary

    Modifier and Type
    Method
    Description
    Generate a copy of this Image, except with different coordinates.
    copyWith(Coords coords, Metadata metadata)
    Generate a copy of this Image, except with different coordinates and metadata.
    Generate a copy of this Image, except with different metadata.
    byte[]
    Regardless of the the value of #getBytesPerPixel return an array of bytes containing raw data for the image.
    int
    Return the number of bytes used to represent each pixel component of this image.
    int
    Return the number of bytes used to represent each pixel of this image.
    long[]
    Returns the pixel intensity of all components.
    long
    getComponentIntensityAt(int x, int y, int component)
    Get the intensity of a component of the pixel at the specified position.
    Retrieve the Coords of this Image.
    int
    Get the height of this image in pixels.
    int
    Deprecated.
    Unclear what should be used instead.
    long
    getIntensityAt(int x, int y)
    Retrieve the intensity of the pixel at the specified position.
    getIntensityStringAt(int x, int y)
    Generate a string describing the value(s) of the pixel at the specified location.
    Retrieve the Metadata for this Image.
    int
    Get the number of components per pixel in this image.
    Returns the internal pixel data of this image.
    Returns a copy of the raw pixel data that getRawPixels returns.
    getRawPixelsForComponent(int component)
    Return a copy of the raw pixel data for the specified component.
    int
    Get the width of this image in pixels.
  • Method Details

    • copyAtCoords

      Image copyAtCoords(Coords coords)
      Generate a copy of this Image, except with different coordinates.

      Because Image objects are immutable, the "copy" can safely share the pixel data with the original. So this is an efficient operation.

      Parameters:
      coords - Coordinates at which to place the new image.
      Returns:
      The copied image
      See Also:
    • copyWithMetadata

      Image copyWithMetadata(Metadata metadata)
      Generate a copy of this Image, except with different metadata.

      Because Image objects are immutable, the "copy" can safely share the pixel data with the original. So this is an efficient operation.

      Parameters:
      metadata - The new metadata to use for the copy
      Returns:
      The copied image
      See Also:
    • copyWith

      Image copyWith(Coords coords, Metadata metadata)
      Generate a copy of this Image, except with different coordinates and metadata.

      Because Image objects are immutable, the "copy" can safely share the pixel data with the original. So this is an efficient operation.

      Parameters:
      coords - Coordinates at which to place the new image.
      metadata - The new metadata to use for the copy
      Returns:
      The copied image
      See Also:
    • getIntensityAt

      long getIntensityAt(int x, int y)
      Retrieve the intensity of the pixel at the specified position.

      This method is intended for getting a single pixel value (e.g. to see the value at the mouse cursor).

      Equivalent to calling getComponentIntensityAt(x, y, 0). Use this method only in contexts where you are sure you will never handle non-grayscale images.

      Parameters:
      x - X coordinate at which to retrieve image data
      y - Y coordinate at which to retrieve image data
      Returns:
      intensity of the image at the specified coordinates
      Throws:
      IndexOutOfBoundsException - when the index is out of bounds
      See Also:
    • getComponentIntensityAt

      long getComponentIntensityAt(int x, int y, int component)
      Get the intensity of a component of the pixel at the specified position.
      Parameters:
      x - X coordinate at which to retrieve image data
      y - Y coordinate at which to retrieve image data
      component - The component number to retrieve intensity for, starting from 0.
      Returns:
      intensity of the image at the specified coordinates, for the given component
      Throws:
      IndexOutOfBoundsException - when the index is out of bounds
      See Also:
    • getComponentIntensitiesAt

      long[] getComponentIntensitiesAt(int x, int y)
      Returns the pixel intensity of all components.
      Parameters:
      x - Pixel location along x axis.
      y - Pixel location along y axis.
      Returns:
      Intensity of the component.
      Throws:
      IndexOutOfBoundsException - when the pixel location does not exist.
      See Also:
    • getImageJPixelType

      @Deprecated int getImageJPixelType()
      Deprecated.
      Unclear what should be used instead. Do not delete until this is figure out.
      Return the ImageJ pixel type enum constant.

      The constants are defined in ImagePlus: GRAY8, GRAY16, COLOR_RGB.

      Returns:
      ImageJ pixel type.
      Throws:
      UnsupportedOperationException - if the image format is not supported by ImageJ1
    • getIntensityStringAt

      String getIntensityStringAt(int x, int y)
      Generate a string describing the value(s) of the pixel at the specified location.

      The string will be a plain number for single-component images, and an "(A, B, C)"-formatted string for multi-component images. (The string format may change in the future.)

      Parameters:
      x - X coordinate at which to retrieve image data
      y - Y coordinate at which to retrieve image data
      Returns:
      A string describing the pixel intensity/intensities at the given coordinates.
    • getMetadata

      Metadata getMetadata()
      Retrieve the Metadata for this Image.
      Returns:
      The image metadata.
    • getCoords

      Coords getCoords()
      Retrieve the Coords of this Image.
      Returns:
      The image coordinates.
    • getWidth

      int getWidth()
      Get the width of this image in pixels.
      Returns:
      The width of the image in pixels.
    • getHeight

      int getHeight()
      Get the height of this image in pixels.
      Returns:
      The height of the image in pixels.
    • getBytesPerPixel

      int getBytesPerPixel()
      Return the number of bytes used to represent each pixel of this image.

      Note that this does not necessarily match 8 times the bit depth of the image, since images may have lower bit depth than the samples used.

      For multi-component images, the bytes per pixel may be greater than the number of components times the bytes per component, if padding is used.

      Returns:
      size of pixel in bytes
    • getBytesPerComponent

      int getBytesPerComponent()
      Return the number of bytes used to represent each pixel component of this image.
      Returns:
      size of component in bytes
    • getNumComponents

      int getNumComponents()
      Get the number of components per pixel in this image.

      The return value is 1 for grayscale images and 3 for RGB images.

      Returns:
      number of sample components
    • getRawPixels

      Object getRawPixels()
      Returns the internal pixel data of this image.

      The returned value may or may not be a copy of the internal pixel data.

      Warning: Do not depend on the type of the object returned. It may change in the future. Also, never modify the returned object!

      Returns:
      An array of pixel values for the image data
      See Also:
    • getRawPixelsCopy

      Object getRawPixelsCopy()
      Returns a copy of the raw pixel data that getRawPixels returns.

      Use if you need to modify the pixel data.

      Warning: Do not depend on the type of the object returned. It may change in the future.

      Returns:
      An array of pixel values for the image data, copied from the original data.
    • getRawPixelsForComponent

      Object getRawPixelsForComponent(int component)
      Return a copy of the raw pixel data for the specified component.

      As getRawPixelsCopy, but will split out the specified component for multi-component images. Use of this method could potentially impair performance as the image data must be de-interleaved. Calling this on a single-component image with an argument of 0 is equivalent to calling getRawPixelsCopy.

      Parameters:
      component - The component number, starting from 0
      Returns:
      An array of pixel values for the specified component
      See Also:
    • getByteArray

      byte[] getByteArray()
      Regardless of the the value of #getBytesPerPixel return an array of bytes containing raw data for the image. Useful for doing low-level handling of raw image data. The returned array is a copy of the original data.
      Returns:
      The byte array containing a copy of the raw data for this image.