001/*
002 * $RCSfile: ImgData.java,v $
003 * $Revision: 1.1 $
004 * $Date: 2005/02/11 05:02:12 $
005 * $State: Exp $
006 *
007 * Interface:           ImgData
008 *
009 * Description:         The interface for classes that provide image
010 *                      data.
011 *
012 *
013 *
014 * COPYRIGHT:
015 *
016 * This software module was originally developed by Raphaël Grosbois and
017 * Diego Santa Cruz (Swiss Federal Institute of Technology-EPFL); Joel
018 * Askelöf (Ericsson Radio Systems AB); and Bertrand Berthelot, David
019 * Bouchard, Félix Henry, Gerard Mozelle and Patrice Onno (Canon Research
020 * Centre France S.A) in the course of development of the JPEG2000
021 * standard as specified by ISO/IEC 15444 (JPEG 2000 Standard). This
022 * software module is an implementation of a part of the JPEG 2000
023 * Standard. Swiss Federal Institute of Technology-EPFL, Ericsson Radio
024 * Systems AB and Canon Research Centre France S.A (collectively JJ2000
025 * Partners) agree not to assert against ISO/IEC and users of the JPEG
026 * 2000 Standard (Users) any of their rights under the copyright, not
027 * including other intellectual property rights, for this software module
028 * with respect to the usage by ISO/IEC and Users of this software module
029 * or modifications thereof for use in hardware or software products
030 * claiming conformance to the JPEG 2000 Standard. Those intending to use
031 * this software module in hardware or software products are advised that
032 * their use may infringe existing patents. The original developers of
033 * this software module, JJ2000 Partners and ISO/IEC assume no liability
034 * for use of this software module or modifications thereof. No license
035 * or right to this software module is granted for non JPEG 2000 Standard
036 * conforming products. JJ2000 Partners have full right to use this
037 * software module for his/her own purpose, assign or donate this
038 * software module to any third party and to inhibit third parties from
039 * using this software module for non JPEG 2000 Standard conforming
040 * products. This copyright notice must be included in all copies or
041 * derivative works of this software module.
042 *
043 * Copyright (c) 1999/2000 JJ2000 Partners.
044 *
045 *
046 *
047 */
048
049package jj2000.j2k.image;
050
051import java.awt.Point;
052/**
053 * This interface defines methods to access image attributes (width, height,
054 * number of components, etc.). The image can be tiled or not (i.e. if the
055 * image is not tiled then there is only 1 tile). It should be implemented by
056 * all classes that provide image data, such as image file readers, color
057 * transforms, wavelet transforms, etc. This interface, however, does not
058 * define methods to transfer image data (i.e. pixel data), that is defined by
059 * other interfaces, such as 'BlkImgDataSrc'.
060 *
061 * @see BlkImgDataSrc
062 * */
063public interface ImgData {
064    /**
065     * Returns the overall width of the current tile in pixels. This is the
066     * tile's width without accounting for any component subsampling. This is
067     * also referred as the reference grid width in the current tile.
068     *
069     * @return The total current tile's width in pixels.
070     * */
071    public int getTileWidth();
072
073    /**
074     * Returns the overall height of the current tile in pixels. This is the
075     * tile's height without accounting for any component subsampling. This is
076     * also referred as the reference grid height in the current tile.
077     *
078     * @return The total current tile's height in pixels.
079     * */
080    public int getTileHeight();
081
082    /** Returns the nominal tiles width */
083    public int getNomTileWidth();
084
085    /** Returns the nominal tiles height */
086    public int getNomTileHeight();
087
088    /**
089     * Returns the overall width of the image in pixels. This is the image's
090     * width without accounting for any component subsampling or tiling.
091     *
092     * @return The total image's width in pixels.
093     * */
094    public int getImgWidth();
095
096    /**
097     * Returns the overall height of the image in pixels. This is the image's
098     * height without accounting for any component subsampling or tiling.
099     *
100     * @return The total image's height in pixels.
101     * */
102    public int getImgHeight();
103
104    /**
105     * Returns the number of components in the image.
106     *
107     * @return The number of components in the image.
108     * */
109    public int getNumComps();
110
111    /**
112     * Returns the component subsampling factor in the horizontal direction,
113     * for the specified component. This is, approximately, the ratio of
114     * dimensions between the reference grid and the component itself, see the
115     * 'ImgData' interface desription for details.
116     *
117     * @param c The index of the component (between 0 and N-1)
118     *
119     * @return The horizontal subsampling factor of component 'c'
120     *
121     * @see ImgData
122     * */
123    public int getCompSubsX(int c);
124
125    /**
126     * Returns the component subsampling factor in the vertical direction, for
127     * the specified component. This is, approximately, the ratio of
128     * dimensions between the reference grid and the component itself, see the
129     * 'ImgData' interface desription for details.
130     *
131     * @param c The index of the component (between 0 and N-1)
132     *
133     * @return The vertical subsampling factor of component 'c'
134     *
135     * @see ImgData
136     * */
137    public int getCompSubsY(int c);
138
139    /**
140     * Returns the width in pixels of the specified tile-component
141     *
142     * @param t Tile index
143     *
144     * @param c The index of the component, from 0 to N-1.
145     *
146     * @return The width in pixels of component <tt>c</tt> in tile<tt>t</tt>.
147     * */
148    public int getTileCompWidth(int t,int c);
149
150    /**
151     * Returns the height in pixels of the specified tile-component.
152     *
153     * @param t The tile index.
154     *
155     * @param c The index of the component, from 0 to N-1.
156     *
157     * @return The height in pixels of component <tt>c</tt> in tile
158     * <tt>t</tt>.
159     * */
160    public int getTileCompHeight(int t,int c);
161
162    /**
163     * Returns the width in pixels of the specified component in the overall
164     * image.
165     *
166     * @param c The index of the component, from 0 to N-1.
167     *
168     * @return The width in pixels of component <tt>c</tt> in the overall
169     * image.
170     * */
171    public int getCompImgWidth(int c);
172
173    /**
174     * Returns the height in pixels of the specified component in the overall
175     * image.
176     *
177     * @param c The index of the component, from 0 to N-1.
178     *
179     * @return The height in pixels of component <tt>n</tt> in the overall
180     * image.
181     * */
182    public int getCompImgHeight(int c);
183
184    /**
185     * Returns the number of bits, referred to as the "range bits",
186     * corresponding to the nominal range of the image data in the specified
187     * component. If this number is <i>n</b> then for unsigned data the
188     * nominal range is between 0 and 2^b-1, and for signed data it is between
189     * -2^(b-1) and 2^(b-1)-1. In the case of transformed data which is not in
190     * the image domain (e.g., wavelet coefficients), this method returns the
191     * "range bits" of the image data that generated the coefficients.
192     *
193     * @param c The index of the component.
194     *
195     * @return The number of bits corresponding to the nominal range of the
196     * image data (in the image domain).
197     * */
198    public int getNomRangeBits(int c);
199    /**
200     * Changes the current tile, given the new indices. An
201     * IllegalArgumentException is thrown if the coordinates do not correspond
202     * to a valid tile.
203     *
204     * @param x The horizontal index of the tile.
205     *
206     * @param y The vertical index of the new tile.
207     * */
208    public void setTile(int x,int y);
209
210    /**
211     * Advances to the next tile, in standard scan-line order (by rows then
212     * columns). An NoNextElementException is thrown if the current tile is
213     * the last one (i.e. there is no next tile).
214     * */
215    public void nextTile();
216
217    /**
218     * Returns the indixes of the current tile. These are the horizontal and
219     * vertical indexes of the current tile.
220     *
221     * @param co If not null this object is used to return the information. If
222     * null a new one is created and returned.
223     *
224     * @return The current tile's indices (vertical and horizontal indexes).
225     * */
226    public Point getTile(Point co);
227
228    /**
229     * Returns the index of the current tile, relative to a standard scan-line
230     * order.
231     *
232     * @return The current tile's index (starts at 0).
233     * */
234    public int getTileIdx();
235
236    /** Returns the horizontal tile partition offset in the reference grid */
237    public int getTilePartULX();
238
239    /** Returns the vertical tile partition offset in the reference grid */
240    public int getTilePartULY();
241
242    /**
243     * Returns the horizontal coordinate of the upper-left corner of the
244     * specified component in the current tile.
245     *
246     * @param c The index of the component.
247     * */
248    public int getCompULX(int c);
249
250    /**
251     * Returns the vertical coordinate of the upper-left corner of the
252     * specified component in the current tile.
253     *
254     * @param c The index of the component.
255     * */
256    public int getCompULY(int c);
257
258    /**
259     * Returns the horizontal coordinate of the image origin, the top-left
260     * corner, in the canvas system, on the reference grid.
261     *
262     * @return The horizontal coordinate of the image origin in the canvas
263     * system, on the reference grid.
264     * */
265    public int getImgULX();
266
267    /**
268     * Returns the vertical coordinate of the image origin, the top-left
269     * corner, in the canvas system, on the reference grid.
270     *
271     * @return The vertical coordinate of the image origin in the canvas
272     * system, on the reference grid.
273     * */
274    public int getImgULY();
275
276    /**
277     * Returns the number of tiles in the horizontal and vertical directions.
278     *
279     * @param co If not null this object is used to return the information. If
280     * null a new one is created and returned.
281     *
282     * @return The number of tiles in the horizontal (Point.x) and vertical
283     * (Point.y) directions.
284     * */
285    public Point getNumTiles(Point co);
286
287    /**
288     * Returns the total number of tiles in the image.
289     *
290     * @return The total number of tiles in the image.
291     * */
292    public int getNumTiles();
293
294}