Package net.sourceforge.jiu.data

# Interface BilevelImage

All Superinterfaces:
  `GrayImage`, `GrayIntegerImage`, `IntegerImage`, `PixelImage`

All Known Implementing Classes:
  `MemoryBilevelImage`

public interface BilevelImage extends GrayIntegerImage
An interface for bilevel pixel image data classes. Each pixel in a bilevel image can have two possible values, `BLACK` and `WHITE`. Those two constants are guaranteed to be `0` and `1`, although you should not make any assumptions about what value any of the two constants has. This is the type of image used for faxes. Black and white photos are usually stored as grayscale images.

Apart from implementing `PixelImage` - like all image data classes in JIU - this interface is also an `IntegerImage` (each sample is either 0 or 1) and a `GrayImage` (black and white are both grayscale values). The combination of `IntegerImage` and `GrayImage` is `GrayIntegerImage`, which is the direct superinterface of this interface.

### Packed bytes

There are methods to get and put packed bytes in this interface. A packed byte is a `byte` value that stores eight horizontally neighbored bilevel pixels in it (pixel and sample can be used interchangeably in the context of bilevel images because there is only one sample per pixel). The most significant bit of such a packed bit is defined to be the leftmost of the eight pixels, the second-most significant bit is the pixel to the right of that leftmost pixel, and so on. The least significant bit is the rightmost pixel. If a bit is set, the corresponing pixel value is supposed to be white, otherwise black.

### Usage examples

Here are some code examples that demonstrate how to access image data with this class.

     BilevelImage image = new MemoryBilevelImage(2000, 500);
     // now set all pixels in the first row to white
     for (int x = 0; x < image.getWidth(); x++)
     {
       image.putWhite(x, 0);
     }
     // put vertical stripes on the rest
     for (int y = 1; y < image.getHeight(); y++)
     {
       for (int x = 0; x < image.getWidth(); x++)
       {
         int sample;
         if ((x % 2) == 0)
         {
           sample = BilevelImage.BLACK;
         }
         else
         {
           sample = BilevelImage.WHITE;
         }
         image.putSample(x, y, sample);
       }
     }

Author:
  Marco Schmidt

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`BLACK`
The value for a black pixel.
`static final int`
`WHITE`
The value for a white pixel.

## Method Summary

Modifier and Type
Method
Description
`void`
`getPackedBytes(int x, int y, int numSamples, byte[] dest, int destOffset, int destBitOffset)`
Sets a number of samples in the argument array from this image.
`void`
`putPackedBytes(int x, int y, int numSamples, byte[] src, int srcOffset, int srcBitOffset)`
Sets a number of samples in the image from the argument array data.

### Methods inherited from interface net.sourceforge.jiu.data.GrayImage

`isBlack, isWhite, putBlack, putWhite`

### Methods inherited from interface net.sourceforge.jiu.data.IntegerImage

`clear, clear, getMaxSample, getSample, getSample, getSamples, putSample, putSample, putSamples`

### Methods inherited from interface net.sourceforge.jiu.data.PixelImage

`createCompatibleImage, createCopy, getAllocatedMemory, getBitsPerPixel, getHeight, getImageType, getNumChannels, getWidth`

## Field Details

### BLACK

static final int BLACK
The value for a black pixel. To be used with all methods that require `int` arguments for sample values. You can rely on this value being either 0 or 1 (that way you can safely store it in a byte or short).

See Also:
  - Constant Field Values

### WHITE

static final int WHITE
The value for a white pixel. To be used with all methods that require `int` arguments for sample values. You can rely on this value being either 0 or 1 (that way you can safely store it in a byte or short).

See Also:
  - Constant Field Values

## Method Details

### getPackedBytes

void getPackedBytes(int x, int y, int numSamples, byte[] dest, int destOffset, int destBitOffset)
Sets a number of samples in the argument array from this image.

Parameters:
  `x` - horizontal position of first sample of this image to read
  `y` - vertical position of samples to be read from this image
  `numSamples` - number of samples to be set
  `dest` - array with packed pixels to which samples are copied
  `destOffset` - index into dest array of the first byte value to write sample values to
  `destBitOffset` - index of first bit of `dest[destOffset]` to write a sample to (0 is leftmost, 1 is second-leftmost up to 7, which is the rightmost)

### putPackedBytes

void putPackedBytes(int x, int y, int numSamples, byte[] src, int srcOffset, int srcBitOffset)
Sets a number of samples in the image from the argument array data.

Parameters:
  `x` - horizontal position of first sample to be set
  `y` - vertical position of samples to be set
  `numSamples` - number of samples to be set
  `src` - array with packed pixels to be set
  `srcOffset` - index into src array of the first byte value to read sample values from
  `srcBitOffset` - index of first bit of `src[srcOffset]` to read a sample from (0 is leftmost, 1 is second-leftmost up to 7, which is the rightmost)