001 /* 002 * BilevelImage 003 * 004 * Copyright (c) 2000, 2001, 2002, 2003 Marco Schmidt. 005 * All rights reserved. 006 */ 007 008 package net.sourceforge.jiu.data; 009 010 import net.sourceforge.jiu.data.GrayIntegerImage; 011 012 /** 013 * An interface for bilevel pixel image data classes. 014 * Each pixel in a bilevel image can have two possible values, {@link #BLACK} and {@link #WHITE}. 015 * Those two constants are guaranteed to be <code>0</code> and <code>1</code>, although 016 * you should not make any assumptions about what value any of the two constants has. 017 * This is the type of image used for faxes. 018 * Black and white photos are usually stored as grayscale images. 019 * <p> 020 * Apart from implementing {@link PixelImage} - like all image data classes in JIU - 021 * this interface is also an {@link IntegerImage} (each sample is either 0 or 1) and 022 * a {@link GrayImage} (black and white are both grayscale values). 023 * The combination of {@link IntegerImage} and {@link GrayImage} is {@link GrayIntegerImage}, 024 * which is the direct superinterface of this interface. 025 * 026 * <h3>Packed bytes</h3> 027 * 028 * There are methods to get and put <em>packed bytes</em> in this interface. 029 * A packed byte is a <code>byte</code> value that stores eight horizontally neighbored bilevel 030 * pixels in it (pixel and sample can be used interchangeably in the context of bilevel images 031 * because there is only one sample per pixel). 032 * The most significant bit of such a packed bit is defined to be the leftmost of the 033 * eight pixels, the second-most significant bit is the pixel to the right of that leftmost pixel, 034 * and so on. The least significant bit is the rightmost pixel. 035 * If a bit is set, the corresponing pixel value is supposed to be white, otherwise black. 036 * 037 * <h3>Usage examples</h3> 038 * 039 * Here are some code examples that demonstrate how to access image data with this class. 040 * <pre> 041 * BilevelImage image = new MemoryBilevelImage(2000, 500); 042 * // now set all pixels in the first row to white 043 * for (int x = 0; x < image.getWidth(); x++) 044 * { 045 * image.putWhite(x, 0); 046 * } 047 * // put vertical stripes on the rest 048 * for (int y = 1; y < image.getHeight(); y++) 049 * { 050 * for (int x = 0; x < image.getWidth(); x++) 051 * { 052 * int sample; 053 * if ((x % 2) == 0) 054 * { 055 * sample = BilevelImage.BLACK; 056 * } 057 * else 058 * { 059 * sample = BilevelImage.WHITE; 060 * } 061 * image.putSample(x, y, sample); 062 * } 063 * } 064 * </pre> 065 * 066 * @author Marco Schmidt 067 */ 068 public interface BilevelImage extends GrayIntegerImage 069 { 070 /** 071 * The value for a black pixel. 072 * To be used with all methods that require <code>int</code> arguments for sample values. 073 * You can rely on this value being either 0 or 1 (that way you can safely store it 074 * in a byte or short). 075 */ 076 int BLACK = 0; 077 078 /** 079 * The value for a white pixel. 080 * To be used with all methods that require <code>int</code> arguments for sample values. 081 * You can rely on this value being either 0 or 1 (that way you can safely store it 082 * in a byte or short). 083 */ 084 int WHITE = 1; 085 086 /** 087 * Sets a number of samples in the argument array from this image. 088 * @param x horizontal position of first sample of this image to read 089 * @param y vertical position of samples to be read from this image 090 * @param numSamples number of samples to be set 091 * @param dest array with packed pixels to which samples are copied 092 * @param destOffset index into dest array of the first byte value to write sample values to 093 * @param destBitOffset index of first bit of <code>dest[destOffset]</code> to write a sample to (0 is leftmost, 1 is second-leftmost up to 7, which is the rightmost) 094 */ 095 void getPackedBytes(int x, int y, int numSamples, byte[] dest, int destOffset, int destBitOffset); 096 097 /** 098 * Sets a number of samples in the image from the argument array data. 099 * @param x horizontal position of first sample to be set 100 * @param y vertical position of samples to be set 101 * @param numSamples number of samples to be set 102 * @param src array with packed pixels to be set 103 * @param srcOffset index into src array of the first byte value to read sample values from 104 * @param srcBitOffset index of first bit of <code>src[srcOffset]</code> to 105 * read a sample from (0 is leftmost, 1 is second-leftmost up to 7, which is the rightmost) 106 */ 107 void putPackedBytes(int x, int y, int numSamples, byte[] src, int srcOffset, int srcBitOffset); 108 }