org.micromanager.data

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 and Description
Image	copyAtCoords(Coords coords) Generate a copy of this Image, except with different coordinates.
Image	copyWith(Coords coords, Metadata metadata) Generate a copy of this Image, except with different coordinates and metadata.
Image	copyWithMetadata(Metadata metadata) Generate a copy of this Image, except with different metadata.
byte[]	getByteArray() Regardless of the the value of #getBytesPerPixel return an array of bytes containing raw data for the image.
int	getBytesPerComponent() Return the number of bytes used to represent each pixel component of this image.
int	getBytesPerPixel() Return the number of bytes used to represent each pixel of this image.
long[]	getComponentIntensitiesAt(int x, int y) 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.
Coords	getCoords() Retrieve the Coords of this Image.
int	getHeight() Get the height of this image in pixels.
int	getImageJPixelType() Deprecated. Unclear what should be used instead. Do not delete until this is figure out.
long	getIntensityAt(int x, int y) Retrieve the intensity of the pixel at the specified position.
java.lang.String	getIntensityStringAt(int x, int y) Generate a string describing the value(s) of the pixel at the specified location.
Metadata	getMetadata() Retrieve the Metadata for this Image.
int	getNumComponents() Get the number of components per pixel in this image.
java.lang.Object	getRawPixels() Returns the internal pixel data of this image.
java.lang.Object	getRawPixelsCopy() Returns a copy of the raw pixel data that getRawPixels returns.
java.lang.Object	getRawPixelsForComponent(int component) Return a copy of the raw pixel data for the specified component.
int	getWidth() Get the width of this image in pixels.

Method Detail

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:

copyWith(org.micromanager.data.Coords, org.micromanager.data.Metadata)

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(org.micromanager.data.Coords, org.micromanager.data.Metadata)

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:

copyAtCoords(org.micromanager.data.Coords), copyWithMetadata(org.micromanager.data.Metadata)

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:

java.lang.IndexOutOfBoundsException - when the index is out of bounds

See Also:

getComponentIntensityAt(int, int, int), getComponentIntensitiesAt(int, int)

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:

java.lang.IndexOutOfBoundsException - when the index is out of bounds

See Also:

getComponentIntensitiesAt(int, int)

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:

java.lang.IndexOutOfBoundsException - when the pixel location does not exist.

See Also:

getComponentIntensityAt(int, int, int)

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:

java.lang.UnsupportedOperationException - if the image format is not supported by ImageJ1

getIntensityStringAt

java.lang.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

java.lang.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()

getRawPixelsCopy

java.lang.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

java.lang.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:

getRawPixelsCopy()

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.