Package net.sourceforge.jiu.codecs

# Class BMPCodec

java.lang.Object
net.sourceforge.jiu.ops.Operation
net.sourceforge.jiu.codecs.ImageCodec
net.sourceforge.jiu.codecs.BMPCodec

public class BMPCodec extends ImageCodec
A codec to read and write Windows BMP image files.

Typical file extensions are `.bmp` and `.rle` (the latter is only used for compressed files).

### Bounds

This codec supports the bounds concept for loading and saving.

### Supported BMP types when loading

- Bilevel, 1 bit per pixel, uncompressed. BMP supports palettes for bilevel images, but the content of that palette is ignored and 0 is considered black and 1 white. Any class implementing `BilevelImage` can be given to the codec and it will load the image to that object (if the image's resolution is sufficient). If no image object is given to the codec, a new `MemoryBilevelImage` will be created.
- Paletted, 4 bits per pixel, uncompressed or RLE4 compression. Both types are loaded to a `Paletted8Image` object. This requires 50 % more space than is necessary, but there is no dedicated 4 bit image data class in JIU.
- Paletted, 8 bits per pixel, uncompressed or RLE8 compression. Both types are loaded to a `Paletted8Image` object.
- RGB truecolor, 24 bits per pixel, uncompressed. This is loaded to a `RGB24Image` object.

There is no support for 16 bpp images or BI_BITFIELDS compression (for lack of test files).

### Supported JIU image data classes when saving to BMP

- `BilevelImage` objects are stored as 1 bit per pixel BMP files.
- `Gray8Image` and `Paletted8Image` objects are stored as paletted 8 bits per pixel files. It doesn't really matter how many entries the palette has, the BMP file's palette will always have 256 entries, filled up with zero entries if necessary.
- `RGB24Image` objects are stored as 24 bpp BMP files.

There is no support for compressed BMP files when saving.

### I/O classes

BMPCodec works with all input and output classes supported by ImageCodec (`InputStream`, `OutputStream`, `DataInput`, `DataOutput`, `RandomAccessFile`).

### Problems

The RLE-compressed BMP files that I could test this codec on seem to have an end-of-line code at the end of every line instead of relying on the decoder to know when it has unpacked enough bytes for a line. Whenever this codec encounters an EOL symbol and has a current column value of `0`, the EOL is ignored.

### Usage examples

Write an image to a BMP file.

     BMPCodec codec = new BMPCodec();
     codec.setImage(image);
     codec.setFile("out.bmp", CodecMode.SAVE);
     codec.process();
     codec.close();

Read an image from a BMP file.

     BMPCodec codec = new BMPCodec();
     codec.setFile("image.bmp", CodecMode.LOAD);
     codec.process();
     codec.close();
     PixelImage image = codec.getImage();

Since:
  0.7.0
Author:
  Marco Schmidt

## Field Summary

Fields
Modifier and Type
Field
Description
`private int`
`colorDepth`
`private int`
`compression`
`private int`
`dataOffset`
`private int`
`imageHeight`
`private int`
`imageWidth`
`private DataInput`
`in`
`private DataOutput`
`out`
`private Palette`
`palette`

## Constructor Summary

Constructors
Constructor
Description
`BMPCodec()`

## Method Summary

Modifier and Type
Method
Description
`String[]`
`getFileExtensions()`
Returns all file extensions that are typical for this file format.
`String`
`getFormatName()`
Returns the name of the file format supported by this codec.
`String[]`
`getMimeTypes()`
Return the MIME (Multipurpose Internet Mail Extensions) type strings for this format, or `null` if none are available.
`boolean`
`isLoadingSupported()`
Returns if this codec is able to load images in the file format supported by this codec.
`boolean`
`isSavingSupported()`
Returns if this codec is able to save images in the file format supported by this codec.
`private void`
`load()`
`private void`
`loadCompressedPaletted4Stream()`
`private void`
`loadCompressedPaletted8Stream()`
`private void`
`loadHeader()`
`private void`
`loadStream()`
`private void`
`loadUncompressedBilevelStream()`
`private void`
`loadUncompressedPaletted4Stream()`
`private void`
`loadUncompressedPaletted8Stream()`
`private void`
`loadUncompressedRgb24Stream()`
`private void`
`loadUncompressedStream()`
`void`
`process()`
This method does the actual work of the operation.
`private void`
`save()`
`String`
`suggestFileExtension(PixelImage image)`
Attempts to suggest a filename extension.
`private void`
`writeHeader(PixelImage image, int filesize, int offset, int numBits)`
`private void`
`writeInt(int value)`
`private void`
`writePalette()`
Write the palette associated with the image getImage().
`private void`
`writeShort(int value)`
`private void`
`writeStream()`

### Methods inherited from class net.sourceforge.jiu.codecs.ImageCodec

`appendComment, checkBounds, checkImageResolution, close, getBoundsHeight, getBoundsWidth, getBoundsX1, getBoundsX2, getBoundsY1, getBoundsY2, getComment, getDataInput, getDataOutput, getDpiX, getDpiY, getImage, getImageIndex, getInputAsDataInput, getInputStream, getMode, getNumComments, getOutputAsDataOutput, getOutputStream, getRandomAccessFile, hasBounds, initModeFromIOObjects, isRowRequired, isTileRequired, removeAllComments, removeBounds, setBounds, setBoundsIfNecessary, setDataInput, setDataOutput, setDpi, setFile, setFile, setImage, setImageIndex, setInputStream, setOutputStream, setRandomAccessFile`

### Methods inherited from class net.sourceforge.jiu.ops.Operation

`addProgressListener, addProgressListeners, getAbort, removeProgressListener, setAbort, setProgress, setProgress`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### colorDepth

private int colorDepth

### compression

private int compression

### dataOffset

private int dataOffset

### imageHeight

private int imageHeight

### imageWidth

private int imageWidth

### in

private DataInput in

### out

private DataOutput out

### palette

private Palette palette

## Constructor Details

### BMPCodec

public BMPCodec()

## Method Details

### getFileExtensions

public String[] getFileExtensions()
Description copied from class: `ImageCodec`
Returns all file extensions that are typical for this file format. The default implementation in ImageCodec returns `null`. The file extension strings should include a leading dot and are supposed to be lower case (if that is allowed for the given file format). Example: `{".jpg", ".jpeg"}` for the JPEG file format.

Overrides:
  `getFileExtensions` in class `ImageCodec`
Returns:
  String array with typical file extensions

### getFormatName

public String getFormatName()
Description copied from class: `ImageCodec`
Returns the name of the file format supported by this codec. All classes extending `ImageCodec` must override this method. When overriding, leave out any words in a particular language so that this format name can be understood by everyone. Usually it is enough to return the format creator plus a typical abbreviation, e.g. `Microsoft BMP` or `Portable Anymap (PNM)`.

Specified by:
  `getFormatName` in class `ImageCodec`
Returns:
  name of the file format supported by this codec

### getMimeTypes

public String[] getMimeTypes()
Description copied from class: `ImageCodec`
Return the MIME (Multipurpose Internet Mail Extensions) type strings for this format, or `null` if none are available.

Specified by:
  `getMimeTypes` in class `ImageCodec`
Returns:
  MIME type strings or null

### isLoadingSupported

public boolean isLoadingSupported()
Description copied from class: `ImageCodec`
Returns if this codec is able to load images in the file format supported by this codec. If `true` is returned this does not necessarily mean that all files in this format can be read, but at least some.

Specified by:
  `isLoadingSupported` in class `ImageCodec`
Returns:
  if loading is supported

### isSavingSupported

public boolean isSavingSupported()
Description copied from class: `ImageCodec`
Returns if this codec is able to save images in the file format supported by this codec. If `true` is returned this does not necessarily mean that all types files in this format can be written, but at least some.

Specified by:
  `isSavingSupported` in class `ImageCodec`
Returns:
  if saving is supported

### load

private void load() throws MissingParameterException, OperationFailedException, UnsupportedTypeException, WrongFileFormatException

Throws:
  `MissingParameterException`
  `OperationFailedException`
  `UnsupportedTypeException`
  `WrongFileFormatException`

### loadCompressedPaletted4Stream

private void loadCompressedPaletted4Stream() throws IOException

Throws:
  `IOException`

### loadCompressedPaletted8Stream

private void loadCompressedPaletted8Stream() throws IOException

Throws:
  `IOException`

### loadHeader

private void loadHeader() throws IOException, MissingParameterException, OperationFailedException, UnsupportedTypeException, WrongFileFormatException

Throws:
  `IOException`
  `MissingParameterException`
  `OperationFailedException`
  `UnsupportedTypeException`
  `WrongFileFormatException`

### loadStream

private void loadStream() throws IOException, MissingParameterException, OperationFailedException, UnsupportedTypeException

Throws:
  `IOException`
  `MissingParameterException`
  `OperationFailedException`
  `UnsupportedTypeException`

### loadUncompressedBilevelStream

private void loadUncompressedBilevelStream() throws IOException, OperationFailedException

Throws:
  `IOException`
  `OperationFailedException`

### loadUncompressedPaletted4Stream

private void loadUncompressedPaletted4Stream() throws IOException

Throws:
  `IOException`

### loadUncompressedPaletted8Stream

private void loadUncompressedPaletted8Stream() throws IOException

Throws:
  `IOException`

### loadUncompressedRgb24Stream

private void loadUncompressedRgb24Stream() throws IOException

Throws:
  `IOException`

### loadUncompressedStream

private void loadUncompressedStream() throws IOException, OperationFailedException

Throws:
  `IOException`
  `OperationFailedException`

### process

public void process() throws MissingParameterException, OperationFailedException
Description copied from class: `Operation`
This method does the actual work of the operation. It must be called after all parameters have been given to the operation object.

Overrides:
  `process` in class `Operation`
Throws:
  `MissingParameterException` - if any mandatory parameter was not given to the operation
  `OperationFailedException`

### save

private void save() throws MissingParameterException, OperationFailedException, UnsupportedTypeException

Throws:
  `MissingParameterException`
  `OperationFailedException`
  `UnsupportedTypeException`

### suggestFileExtension

public String suggestFileExtension(PixelImage image)
Description copied from class: `ImageCodec`
Attempts to suggest a filename extension. The type of the argument image will be taken into consideration, although this will be necessary for some file formats only (as an example, PNM has different extensions for different image types, see `PNMCodec`). This default implementation always returns `null`.

Overrides:
  `suggestFileExtension` in class `ImageCodec`
Parameters:
  `image` - the image that is to be written to a file
Returns:
  the file extension, including a leading dot, or `null` if no file extension can be recommended

### writeHeader

private void writeHeader(PixelImage image, int filesize, int offset, int numBits) throws IOException

Throws:
  `IOException`

### writeInt

private void writeInt(int value) throws IOException

Throws:
  `IOException`

### writePalette

private void writePalette() throws IOException
Write the palette associated with the image getImage(). Required not only for image objects that implement PalettedImage but also for BilevelImage and Grayscale8Image. For the latter two the palette values must be explicitly written into the file.

Throws:
  `IOException`

### writeShort

private void writeShort(int value) throws IOException

Throws:
  `IOException`

### writeStream

private void writeStream() throws IOException

Throws:
  `IOException`