com.atalasoft.imaging
Class AtalaImage

java.lang.Object
  extended by com.atalasoft.imaging.AtalaImage
All Implemented Interfaces:
Disposable, java.lang.Cloneable

public class AtalaImage
extends java.lang.Object
implements java.lang.Cloneable, Disposable

The AtalaImage object holds the raw image data, a Palette, and methods used to access this data.

Image data is stored in a 32-bit row aligned buffer.


Constructor Summary
AtalaImage()
          Initialize a new instance of the AtalaImage class which is 1 x 1 in 24 bit rgb color.
AtalaImage(javax.imageio.stream.ImageInputStream stream)
          Initialize a new instance of a AtalaImage class specifying a ImageInputStream
AtalaImage(javax.imageio.stream.ImageInputStream stream, int frameIndex, ImageDecoder decoder, ProgressEventHandler progress)
          Initialize a new instance of an AtalaImage class specifying a ImageInputStream, ImageDecoder to use for decoding the image, and a progress handler.
AtalaImage(javax.imageio.stream.ImageInputStream stream, int frameIndex, ProgressEventHandler progress)
          Initialize a new instance of a AtalaImage class specifying a ImageInputStream and a page index to decode.
AtalaImage(javax.imageio.stream.ImageInputStream stream, ProgressEventHandler progress)
          Initialize a new instance of an AtalaImage class specifying a ImageInputStream and a progress handler
AtalaImage(int width, int height, PixelFormat pixelFormat)
          Initialize a new instance of the AtalaImage class specifying the Width, Height, and PixelFormat.
AtalaImage(int width, int height, PixelFormat pixelFormat, Color fillColor)
          Initialize a new instance of the AtalaImage class specifying the Width, Height, PixelFormat, and Color to initialize the image background to.
AtalaImage(int width, int height, PixelFormat pixelFormat, int fillPaletteIndex)
          Initialize a new instance of the AtalaImage class specifying the Width, Height, PixelFormat, and Color to initialize the image background to.
AtalaImage(PixelMemory memory, int width, int height, PixelFormat pixelFormat)
          Initialize a new instance of the AtalaImage class specifying the PixelMemory, Width, Height, and PixelFormat.
AtalaImage(java.lang.String fileName)
          Initialize a new instance of a AtalaImage class specifying the file of the image to open.
AtalaImage(java.lang.String fileName, int frameIndex, ProgressEventHandler progress)
          Initialize a new instance of an AtalaImage class specifying an image file and a page index to decode.
AtalaImage(java.lang.String fileName, ProgressEventHandler progress)
          Initialize a new instance of an AtalaImage class specifying an image file and a progress handler.
 
Method Summary
 java.lang.Object clone()
           
static AtalaImage combineChannels(PixelFormat desiredPixelFormat, AtalaImage... channels)
          Combines a set of 8 bit or 16 bit grayscale images into a single AtalaImage with each input image in a channel of the output image.
static void copyBuffer(PixelAccessor paSrc, PixelAccessor paDest)
          Copies raw data from one PixelAccessor to another.
 void dispose()
          Dispose an object's resources.
protected  void dispose(boolean disposing)
           
 void fillRectangle(java.awt.Rectangle rect, Color fillColor)
          Fills a specified rectangle in this image with a specified solid color.
 void fillRectangle(java.awt.Rectangle rect, int fillIndex)
          Fills a specified rectangle in this image with a specified Palette index.
 void flip(java.util.EnumSet<FlipDirection> direction)
          Flips the image in either the horizontal or vertical direction.
static AtalaImage fromBufferedImage(java.awt.image.BufferedImage bi)
          Creates a new AtalaImage from the supplied Java BufferedImage.
 AtalaImage getAllocatedCopy()
          Returns a copy of the image except the image data is allocated, not copied.
 AtalaImage getAllocatedCopy(java.awt.Dimension size)
          Returns an copy of the image except the image data is allocated, not copied.
 AtalaImage getAllocatedCopy(java.awt.Dimension size, Color backgroundColor)
          Returns an copy of the image except the image data is allocated, not copied set to the background color.
 AtalaImage getAllocatedCopy(java.awt.Dimension size, int backgroundPaletteIndex)
          Returns an copy of the image except the image data is allocated, not copied set to the background color.
 AtalaImage getChangedPixelFormat(PixelFormat newPixelFormat)
          Returns a new AtalaImage object with a different PixelFormat from this AtalaImage.
 AtalaImage getChangedPixelFormat(PixelFormat newPixelFormat, ColorProfile destProfile)
          Returns a new AtalaImage object with a different PixelFormat from this AtalaImage.
 int getColorDepth()
          Returns the number of bits per pixel of this AtalaImage.
 ColorProfile getColorProfile()
          Gets the ColorProfile associated with this AtalaImage.
 int getHeight()
          Gets the height of the image in pixels
static AtalaImage getPackedBuffer(AtalaImage image)
          Returns a copy of the source color image into RGB byte order.
 Palette getPalette()
          Returns the Palette object of this AtalaImage.
 CmykColor getPixelCmykColor(int x, int y)
          Gets the color of the pixel at (x, y) as a CmykColor, converting if needed.
 Color getPixelColor(int x, int y)
          Gets the Color of the specified pixel.
 PixelFormat getPixelFormat()
          Gets the PixelFormat of this AtalaImage.
static PixelFormatChanger getPixelFormatChanger()
          Gets the class used to convert image pixel formats.
 int getPixelIndex(int x, int y)
          Gets the palette index for the pixel in the image at (x, y).
 PixelMemory getPixelMemory()
          Provides access to the memory that represents the image.
 Dpi getResolution()
          Gets the resolution of this AtalaImage.
 int getRowStride()
          Get the number of bytes in each row of this AtalaImage
 java.awt.Dimension getSize()
          Gets the size of this image in pixels.
 int getWidth()
          Gets the width of the image in pixels.
 int save(javax.imageio.stream.ImageOutputStream filestream, ImageEncoder encoder, ProgressEventHandler progress)
          Saves this AtalaImage to a ImageOutputStream object specifying an ImageEncoder.
 int save(java.lang.String fileName, ImageEncoder encoder, ProgressEventHandler progress)
          Saves this AtalaImage to a file specifying an ImageEncoder and progress callback.
 void setColorProfile(ColorProfile value)
          Sets the ColorProfile associated with this AtalaImage.
 void setPalette(Palette p)
          Set the Palette object for this AtalaImage.
 void setPixelCmykColor(int x, int y, CmykColor newColor)
          Set the color of a pixel in CMYK space, converting if necessary.
 void setPixelColor(int x, int y, Color newColor)
          Set the color of a pixel in RGB space, converting if possible.
static void setPixelFormatChanger(PixelFormatChanger value)
          Sets the class used to convert image pixel formats.
 void setPixelIndex(int x, int y, byte value)
          Sets the Palette index value for the specified pixel.
 void setResolution(Dpi resolution)
          Sets the resolution of this AtalaImage.
 AtalaImage[] splitChannels(java.util.EnumSet<Channels> channels)
          Returns an array of grayscale AtalaImage objects representing each 8-bit or 16-bit channel in the source image.
 java.awt.image.BufferedImage toBufferedImage()
          Converts an AtalaImage to a Java BufferedImage.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AtalaImage

public AtalaImage()
Initialize a new instance of the AtalaImage class which is 1 x 1 in 24 bit rgb color.


AtalaImage

public AtalaImage(int width,
                  int height,
                  PixelFormat pixelFormat)
Initialize a new instance of the AtalaImage class specifying the Width, Height, and PixelFormat.

Parameters:
width - Width of the image.
height - Height of the image.
pixelFormat - PixelFormat of the image.
Example:
This example will allocate a 100 x 200 1 bit image.

 AtalaImage image = new AtalaImage(100, 200, PixelFormat.PIXEL_1BPP_INDEXED);
 

AtalaImage

public AtalaImage(int width,
                  int height,
                  PixelFormat pixelFormat,
                  Color fillColor)
Initialize a new instance of the AtalaImage class specifying the Width, Height, PixelFormat, and Color to initialize the image background to.

Parameters:
width - Width of the image.
height - Height of the image.
pixelFormat - PixelFormat of the image.
fillColor - The color to fill the image with.

AtalaImage

public AtalaImage(int width,
                  int height,
                  PixelFormat pixelFormat,
                  int fillPaletteIndex)
Initialize a new instance of the AtalaImage class specifying the Width, Height, PixelFormat, and Color to initialize the image background to.

Parameters:
width - Width of the image.
height - Height of the image.
pixelFormat - PixelFormat of the image. Must be one of PIXEL_8BPP_GRAYSCALE, PIXEL_1BPP_INDEXED, PIXEL_4BPP_INDEXED, or PIXEL_8BPP_INDEXED.
fillPaletteIndex - The index from the palette to set as background. Must be in range for the palette.
Throws:
java.lang.IllegalArgumentException - if the pixel format is illegal or the fillPaletteIndex is out of range.

AtalaImage

public AtalaImage(PixelMemory memory,
                  int width,
                  int height,
                  PixelFormat pixelFormat)
Initialize a new instance of the AtalaImage class specifying the PixelMemory, Width, Height, and PixelFormat.

This constructor is typically used if the client has a very specific flavor of PixelMemory to use for an image that would not otherwise be automatically selected.

Parameters:
memory - A PixelMemory object that represents an image's memory.
width - Width of the image.
height - Height of the image.
pixelFormat - PixelFormat of the image. Must be one of PIXEL_8BPP_GRAYSCALE, PIXEL_1BPP_INDEXED, PIXEL_4BPP_INDEXED, or PIXEL_8BPP_INDEXED.

AtalaImage

public AtalaImage(javax.imageio.stream.ImageInputStream stream)
           throws java.io.IOException
Initialize a new instance of a AtalaImage class specifying a ImageInputStream

The appropriate ImageDecoder will be used to read the image.

Parameters:
stream - A stream containing the encoded image data.
Throws:
java.io.IOException - if an I/O error occurs.

AtalaImage

public AtalaImage(javax.imageio.stream.ImageInputStream stream,
                  int frameIndex,
                  ProgressEventHandler progress)
           throws java.io.IOException
Initialize a new instance of a AtalaImage class specifying a ImageInputStream and a page index to decode.

Parameters:
stream - A stream containing the encoded image data.
frameIndex - If the image contains multiple frames, this is the zero based index to load.
progress - The progress delegate. Can be set to null
Throws:
java.io.IOException - if an I/O error occurs.

AtalaImage

public AtalaImage(javax.imageio.stream.ImageInputStream stream,
                  int frameIndex,
                  ImageDecoder decoder,
                  ProgressEventHandler progress)
           throws java.io.IOException
Initialize a new instance of an AtalaImage class specifying a ImageInputStream, ImageDecoder to use for decoding the image, and a progress handler.

Parameters:
stream - A stream containing the encoded image data.
frameIndex - If the image contains multiple frames, this is the zero based index to load.
decoder - The ImageDecoder to use for loading the specified encoded image.
progress - The progress delegate. Can be set to null
Throws:
java.io.IOException - if an I/O error occurs.

AtalaImage

public AtalaImage(javax.imageio.stream.ImageInputStream stream,
                  ProgressEventHandler progress)
           throws java.io.IOException
Initialize a new instance of an AtalaImage class specifying a ImageInputStream and a progress handler

Parameters:
stream - A stream containing the encoded image data.
progress - The progress delegate. Can be set to null
Throws:
java.io.IOException - if an I/O error occurs.

AtalaImage

public AtalaImage(java.lang.String fileName)
           throws java.io.IOException
Initialize a new instance of a AtalaImage class specifying the file of the image to open.

Parameters:
fileName - a path to a file to open
Throws:
java.io.IOException - if an I/O error occurs.

AtalaImage

public AtalaImage(java.lang.String fileName,
                  int frameIndex,
                  ProgressEventHandler progress)
           throws java.io.IOException
Initialize a new instance of an AtalaImage class specifying an image file and a page index to decode.

Parameters:
fileName - a path to a file to open
frameIndex - If the image contains multiple frames, this is the zero based index to load.
progress - The progress delegate. Can be set to null
Throws:
java.io.IOException - if an I/O error occurs.

AtalaImage

public AtalaImage(java.lang.String fileName,
                  ProgressEventHandler progress)
           throws java.io.IOException
Initialize a new instance of an AtalaImage class specifying an image file and a progress handler.

Parameters:
fileName - a path to a file to open
progress - The progress delegate. Can be set to null
Throws:
java.io.IOException - if an I/O error occurs.
Method Detail

save

public int save(java.lang.String fileName,
                ImageEncoder encoder,
                ProgressEventHandler progress)
         throws java.io.IOException
Saves this AtalaImage to a file specifying an ImageEncoder and progress callback.

Parameters:
fileName - The filename to save this AtalaImage to.
encoder - The ImageEncoder which will be used to encode the image.
progress - The progress handler. Can be set to null
Returns:
the number of bytes written.
Throws:
java.io.IOException - if an I/O error occurs.

save

public int save(javax.imageio.stream.ImageOutputStream filestream,
                ImageEncoder encoder,
                ProgressEventHandler progress)
         throws java.io.IOException
Saves this AtalaImage to a ImageOutputStream object specifying an ImageEncoder.

Parameters:
filestream - A stream containing the file which the image will be encoded to.
encoder - The ImageEncoder which will be used to encode the image.
progress - The progress delegate. Can be set to null.
Returns:
The number of bytes saved to the file.
Throws:
java.io.IOException - if an I/O error occurs.

getResolution

public final Dpi getResolution()
Gets the resolution of this AtalaImage.

Returns:
the current image resolution.

setResolution

public final void setResolution(Dpi resolution)
Sets the resolution of this AtalaImage.

Parameters:
resolution - the resolution to set.
Throws:
java.lang.IllegalArgumentException - if resolution is null.

getWidth

public final int getWidth()
Gets the width of the image in pixels.

Returns:
The width of the image in pixels.
See Also:
getHeight(), getSize()

getHeight

public final int getHeight()
Gets the height of the image in pixels

Returns:
The height of the image in pixels
See Also:
getWidth(), getSize()

getSize

public final java.awt.Dimension getSize()
Gets the size of this image in pixels.

Returns:
The size of this image in pixels.
See Also:
getWidth(), getHeight()

getPixelMemory

public final PixelMemory getPixelMemory()
Provides access to the memory that represents the image.

Returns:
An object of type PixelMemory that encapsultes the representation of an image's memory.

getPixelFormat

public final PixelFormat getPixelFormat()
Gets the PixelFormat of this AtalaImage.

Returns:
The PixelFormat of this AtalaImage.
See Also:
for changing the {@link PixelFormat} of the image., for helpful routines for manipulating {@link PixelFormat}.

getRowStride

public final int getRowStride()
Get the number of bytes in each row of this AtalaImage

This value includes number of bytes for all the pixel values in a row and may include padding. Many flavors of PixelMemory use rows padded to 4 bytes.

Returns:
The number of bytes in each row of this image.

getColorDepth

public final int getColorDepth()
Returns the number of bits per pixel of this AtalaImage.

Returns:
The number of bits per pixel of this AtalaImage.

getPalette

public final Palette getPalette()
Returns the Palette object of this AtalaImage.

Returns null if there is no Palette for this image.

Returns:
Returns the palette object of this AtalaImage.

setPalette

public final void setPalette(Palette p)
Set the Palette object for this AtalaImage.

This does not change any pixel values in the image, just how the values are interpreted.

Parameters:
p - the new Palette for this image
Throws:
java.lang.IllegalArgumentException - if p is null.

getColorProfile

public final ColorProfile getColorProfile()
Gets the ColorProfile associated with this AtalaImage.

Returns:
the current ColorProfile.

setColorProfile

public final void setColorProfile(ColorProfile value)
Sets the ColorProfile associated with this AtalaImage.

This is for future use.

Parameters:
value - The new ColorProfile for the image.

getPixelFormatChanger

public static final PixelFormatChanger getPixelFormatChanger()
Gets the class used to convert image pixel formats.

Returns:
An object of type PixelFormatChanger that can be used to convert images from one PixelFormat to another.

setPixelFormatChanger

public static final void setPixelFormatChanger(PixelFormatChanger value)
Sets the class used to convert image pixel formats.

Parameters:
value - An object of type PixelFormatChanger that can be used to convert images from one PixelFormat to another.

This class is used by getChangedPixelFormat(PixelFormat) as well as by all DotImage image commands. By changing this property, a client can control how all pixel format conversions are manager. By default this property is set to an instance of AtalaPixelFormatChanger.

See Also:
AtalaPixelFormatChanger

dispose

public void dispose()
Description copied from interface: Disposable
Dispose an object's resources.

Typical code should be layered into two types of object disposal, disposal due to direct calling of dispose and disposal from the finalizer. These two cases can be distinguised by creating a protected virtual method: protected void dispose(boolean disposing) { } which accepts a boolean that is true if it is being called from the Disposable interface, false if being called by the finalizer. This is because when in the finalizer, it may not be safe to touch any other Disposable objects which may be fields of the current object. Note that Java can be unpredictable as to when, if ever, it calls an object's finalizer. Best practice is to dispose objects at known safe points rather than depend on the garbage collector.

Unlike finalizers, there is nothing that prevents dispose() from being called twice. Protect your objects and their contents appropriately.

Specified by:
dispose in interface Disposable

dispose

protected void dispose(boolean disposing)

clone

public java.lang.Object clone()
Overrides:
clone in class java.lang.Object

getChangedPixelFormat

public final AtalaImage getChangedPixelFormat(PixelFormat newPixelFormat,
                                              ColorProfile destProfile)
Returns a new AtalaImage object with a different PixelFormat from this AtalaImage.

Parameters:
newPixelFormat - The PixelFormat that the new AtalaImage will contain.
destProfile - The color profile to use when converting to and from the CMYK colorspace (future use).
Returns:
A new AtalaImage object with a different %PixelFormat% from this AtalaImage.

getChangedPixelFormat

public final AtalaImage getChangedPixelFormat(PixelFormat newPixelFormat)
Returns a new AtalaImage object with a different PixelFormat from this AtalaImage.

Parameters:
newPixelFormat - The PixelFormat that the new AtalaImage will contain.
Returns:
A new AtalaImage object with a different %PixelFormat% from this AtalaImage.

getPixelIndex

public final int getPixelIndex(int x,
                               int y)
Gets the palette index for the pixel in the image at (x, y).

Parameters:
x - x coordinate in the image.
y - y coordinate in the image.
Returns:
The palette index of the specified pixel.
Throws:
java.lang.IllegalArgumentException - if the (x, y) is not within the boundary of the image.
IncompatiblePixelFormatException - if the pixel format does not have a palette.

getPixelCmykColor

public final CmykColor getPixelCmykColor(int x,
                                         int y)
Gets the color of the pixel at (x, y) as a CmykColor, converting if needed.

Parameters:
x - x coordinate in the image.
y - y coordinate in the image.
Returns:
The color of the pixel as CMYK.
Throws:
java.lang.IllegalArgumentException - if the (x, y) is not within the boundary of the image.

getPixelColor

public final Color getPixelColor(int x,
                                 int y)
Gets the Color of the specified pixel.

Parameters:
x - x coordinate in the image.
y - y coordinate in the image.
Returns:
The Color of the specified pixel.
Throws:
java.lang.IllegalArgumentException - if the (x, y) is not within the boundary of the image.

setPixelCmykColor

public final void setPixelCmykColor(int x,
                                    int y,
                                    CmykColor newColor)
Set the color of a pixel in CMYK space, converting if necessary.

Parameters:
x - x coordinate in the image.
y - y coordinate in the image.
newColor - The desired color in CMYK space.
Throws:
java.lang.IllegalArgumentException - if the (x, y) is not within the boundary of the image.

setPixelColor

public final void setPixelColor(int x,
                                int y,
                                Color newColor)
Set the color of a pixel in RGB space, converting if possible.

Parameters:
x - x coordinate in the image.
y - y coordinate in the image.
newColor - The desired color in RGB space.
Throws:
java.lang.IllegalArgumentException - if the (x, y) is not within the boundary of the image.
IncompatiblePixelFormatException - if the PixelFormat is not a continuous PixelFormat.

splitChannels

public final AtalaImage[] splitChannels(java.util.EnumSet<Channels> channels)
Returns an array of grayscale AtalaImage objects representing each 8-bit or 16-bit channel in the source image.

The returned array contains grayscale images representing the source image channels in the same order as the channels are in the image. Keep in mind that this means a Pixel24bitRgb contains channels in the order of blue, green, and red.

Parameters:
channels - The set of channels to split out. If a channel is not in the set, it will be null in the array.
Returns:
An array of grayscale AtalaImage objects representing specified 8-bit or 16-bit channels in the source image.

flip

public final void flip(java.util.EnumSet<FlipDirection> direction)
Flips the image in either the horizontal or vertical direction.

Parameters:
direction - A set with a single entry for the dlip direction

setPixelIndex

public final void setPixelIndex(int x,
                                int y,
                                byte value)
Sets the Palette index value for the specified pixel.

Parameters:
x - The x coordinate of the pixel.
y - The y coordinate of the pixel.
value - The Palette index to set
Throws:
java.lang.IllegalArgumentException - if x or y are out of range
IncompatiblePixelFormatException - if the image is not an Paletted image or 8 bit gray.

fillRectangle

public final void fillRectangle(java.awt.Rectangle rect,
                                Color fillColor)
Fills a specified rectangle in this image with a specified solid color.

Parameters:
rect - The rectangular area to fill.
fillColor - The color of the fill area.

fillRectangle

public final void fillRectangle(java.awt.Rectangle rect,
                                int fillIndex)
Fills a specified rectangle in this image with a specified Palette index.

Parameters:
rect - The rectangular area to fill.
fillIndex - The palette index or grayscale value to fill.

combineChannels

public static AtalaImage combineChannels(PixelFormat desiredPixelFormat,
                                         AtalaImage... channels)
Combines a set of 8 bit or 16 bit grayscale images into a single AtalaImage with each input image in a channel of the output image.

Parameters:
desiredPixelFormat - The output PixelFormat of the image. This format must have enough channels to contain each of the input channels.
channels - A set of channels to combine into one. Each channel must have the same dimensions
Returns:
a new AtalaImage with combined channels.
Throws:
java.lang.IllegalArgumentException - if there are fewer than 2 or more than 4 channel images, if channel images are not the same size, if the channel images are not 8 or 16 bit grayscale, or the desired PixelFormat doesn't match the bit depth of the channel images.

copyBuffer

public static void copyBuffer(PixelAccessor paSrc,
                              PixelAccessor paDest)
Copies raw data from one PixelAccessor to another.

This is a utility routine that is handy for creating new images that have different row padding since this only copies the minimum number of bytes from each scanline. Source and dest should be the same height.

Parameters:
paSrc - The source PixelAccessor
paDest - The dest PixelAccessor

getAllocatedCopy

public AtalaImage getAllocatedCopy()
Returns a copy of the image except the image data is allocated, not copied.

This will match the size, PixelFormat, ColorProfile and the resolution.

Returns:
A copy of the image, but with blank image data.

getAllocatedCopy

public AtalaImage getAllocatedCopy(java.awt.Dimension size)
Returns an copy of the image except the image data is allocated, not copied.

This will match the PixelFormat, ColorProfile and the resolution.

Parameters:
size - Size of the new image to allocate.
Returns:
A new image in the provided size.

getAllocatedCopy

public AtalaImage getAllocatedCopy(java.awt.Dimension size,
                                   Color backgroundColor)
Returns an copy of the image except the image data is allocated, not copied set to the background color.

This will match the PixelFormat, ColorProfile and the resolution.

Parameters:
size - Size of the new image to allocate.
backgroundColor - The color of the new image.
Returns:
A new image in the provided size.

getAllocatedCopy

public AtalaImage getAllocatedCopy(java.awt.Dimension size,
                                   int backgroundPaletteIndex)
Returns an copy of the image except the image data is allocated, not copied set to the background color.

This will match the PixelFormat, ColorProfile and the resolution.

Parameters:
size - Size of the new image to allocate.
backgroundPaletteIndex - The Palette index to use for the background color.
Returns:
A new image in the provided size.

getPackedBuffer

public static AtalaImage getPackedBuffer(AtalaImage image)
Returns a copy of the source color image into RGB byte order.

Parameters:
image - A source image in BGR byte order
Returns:
A new image in RGB byte order

toBufferedImage

public final java.awt.image.BufferedImage toBufferedImage()
Converts an AtalaImage to a Java BufferedImage.

Returns:
A new BufferedImage that best matches the AtalaImage.

fromBufferedImage

public static final AtalaImage fromBufferedImage(java.awt.image.BufferedImage bi)
Creates a new AtalaImage from the supplied Java BufferedImage.

Not every Java ColorSpace/ColorModel has an exact corresponding PixelFormat. If an approximation can be found that is lossless it will be used. If not an exception will be thrown.

Parameters:
bi - The input buffered image
Returns:
A newly allocated AtalaImage matching the input image.
Throws:
IncompatiblePixelFormatException - if there is no reasonable matching AtalaImage for the format.