001 /*
002 * GeoAPI - Java interfaces for OGC/ISO standards
003 * http://www.geoapi.org
004 *
005 * Copyright (C) 2004-2012 Open Geospatial Consortium, Inc.
006 * All Rights Reserved. http://www.opengeospatial.org/ogc/legal
007 *
008 * Permission to use, copy, and modify this software and its documentation, with
009 * or without modification, for any purpose and without fee or royalty is hereby
010 * granted, provided that you include the following on ALL copies of the software
011 * and documentation or portions thereof, including modifications, that you make:
012 *
013 * 1. The full text of this NOTICE in a location viewable to users of the
014 * redistributed or derivative work.
015 * 2. Notice of any changes or modifications to the OGC files, including the
016 * date changes were made.
017 *
018 * THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE
019 * NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
020 * TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
021 * THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY
022 * PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
023 *
024 * COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
025 * CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
026 *
027 * The name and trademarks of copyright holders may NOT be used in advertising or
028 * publicity pertaining to the software without specific, written prior permission.
029 * Title to copyright in this software and any associated documentation will at all
030 * times remain with copyright holders.
031 */
032 package org.opengis.coverage.grid;
033
034 import java.util.List;
035 import java.awt.image.Raster;
036 import java.awt.image.WritableRaster;
037 import java.awt.image.RenderedImage;
038 import org.opengis.coverage.Coverage;
039 import org.opengis.annotation.UML;
040
041 import static org.opengis.annotation.Obligation.*;
042 import static org.opengis.annotation.Specification.*;
043
044
045 /**
046 * Represent the basic implementation which provides access to grid coverage data.
047 * A {@code GridCoverage} implementation may provide the ability to update
048 * grid values.
049 *
050 * <P> </P>
051 * <TABLE WIDTH="80%" ALIGN="center" CELLPADDING="18" BORDER="4" BGCOLOR="#FFE0B0">
052 * <TR><TD>
053 * <P align="justify"><STRONG>WARNING: THIS CLASS WILL CHANGE.</STRONG> Current API is derived from OGC
054 * <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverages Implementation specification 1.0</A>.
055 * We plan to replace it by new interfaces derived from ISO 19123 (<CITE>Schema for coverage geometry
056 * and functions</CITE>). Current interfaces should be considered as legacy and are included in this
057 * distribution only because they were part of GeoAPI 1.0 release. We will try to preserve as much
058 * compatibility as possible, but no migration plan has been determined yet.</P>
059 * </TD></TR>
060 * </TABLE>
061 *
062 * @version <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverage specification 1.0</A>
063 * @author Martin Desruisseaux (IRD)
064 * @since GeoAPI 1.0
065 *
066 * @see RenderedImage
067 * @see javax.media.jai.PixelAccessor
068 */
069 @UML(identifier="CV_GridCoverage", specification=OGC_01004)
070 public interface GridCoverage extends Coverage {
071 /**
072 * Returns {@code true} if grid data can be edited.
073 *
074 * @return {@code true} if grid data can be edited.
075 */
076 @UML(identifier="dataEditable", obligation=MANDATORY, specification=OGC_01004)
077 boolean isDataEditable();
078
079 /**
080 * Information for the packing of grid coverage values.
081 *
082 * @return The information for the packing of grid coverage values.
083 */
084 @UML(identifier="gridPacking", obligation=MANDATORY, specification=OGC_01004)
085 GridPacking getGridPacking();
086
087 /**
088 * Information for the grid coverage geometry.
089 * Grid geometry includes the valid range of grid coordinates and the georeferencing.
090 *
091 * @return The information for the grid coverage geometry.
092 */
093 @UML(identifier="gridGeometry", obligation=MANDATORY, specification=OGC_01004)
094 GridGeometry getGridGeometry();
095
096 /**
097 * Optimal size to use for each dimension when accessing grid values.
098 * These values together give the optimal block size to use when retrieving
099 * grid coverage values.
100 * For example, a client application can achieve better performance for a 2-D grid
101 * coverage by reading blocks of 128 by 128 if the grid is tiled into blocks of
102 * this size.
103 * The sequence is ordered by dimension.
104 * If the implementation does not have optimal sizes, the sequence will be {@code null}.
105 *
106 * @return The optimal size to use for each dimension when accessing grid values,
107 * or {@code null} if none.
108 */
109 @UML(identifier="optimalDataBlockSizes", obligation=OPTIONAL, specification=OGC_01004)
110 int[] getOptimalDataBlockSizes();
111
112 /**
113 * Number of predetermined overviews for the grid.
114 *
115 * @return The number of predetermined overviews for the grid.
116 */
117 @UML(identifier="numOverviews", obligation=MANDATORY, specification=OGC_01004)
118 int getNumOverviews();
119
120 /**
121 * Returns the grid geometry for an overview.
122 *
123 * @param index Overview index for which to retrieve grid geometry. Indices start at 0.
124 * @return The grid geometry for an overview.
125 * @throws IndexOutOfBoundsException if {@code overviewIndex} is out of bounds.
126 */
127 @UML(identifier="getOverviewGridGeometry", obligation=MANDATORY, specification=OGC_01004)
128 GridGeometry getOverviewGridGeometry(int index) throws IndexOutOfBoundsException;
129
130 /**
131 * Returns a pre-calculated overview for a grid coverage. The overview indices are numbered
132 * from 0 to <code>{@linkplain #getNumOverviews numberOverviews}-1</code>.
133 * The overviews are ordered from highest (index 0) to lowest
134 * (<code>{@linkplain #getNumOverviews numberOverviews}-1</code>) resolution.
135 * Overview grid coverages will have overviews which are the overviews for
136 * the grid coverage with lower resolution than the overview.
137 * For example, a 1 meter grid coverage with 3, 9, and 27 meter overviews
138 * will be ordered as in the left side below. The 3 meter overview will have
139 * 2 overviews as in the right side below:
140 *
141 * <blockquote><table border=0>
142 * <tr>
143 * <th align="center">1 meter GC</th> <th> </th>
144 * <th align="center">3 meter overview</th>
145 * </tr>
146 * <tr>
147 * <td valign="top"><table border=0 align="center">
148 * <tr> <th>Index </th> <th> resolution</th> </tr>
149 * <tr> <td align="center">0</td> <td align="center"> 3</td> </tr>
150 * <tr> <td align="center">1</td> <td align="center"> 9</td> </tr>
151 * <tr> <td align="center">2</td> <td align="center">27</td> </tr>
152 * </table></td>
153 * <td> </td>
154 * <td valign="top"><table border=0 align="center">
155 * <tr> <th>Index </th> <th> resolution</th> </tr>
156 * <tr> <td align="center">0</td> <td align="center"> 9</td> </tr>
157 * <tr> <td align="center">1</td> <td align="center">27</td> </tr>
158 * </table></td>
159 * </table></blockquote>
160 *
161 * @param index Index of grid coverage overview to retrieve. Indexes start at 0.
162 * @return A pre-calculated overview for a grid coverage.
163 * @throws IndexOutOfBoundsException if {@code overviewIndex} is out of bounds.
164 */
165 @UML(identifier="getOverview", obligation=MANDATORY, specification=OGC_01004)
166 GridCoverage getOverview(int index) throws IndexOutOfBoundsException;
167
168 /**
169 * Returns the sources data for a grid coverage. If the {@code GridCoverage} was
170 * produced from an underlying dataset (by {@link GridCoverageReader#read read(...)}
171 * for instance), this method should returns an empty list.
172 *
173 * If the {@code GridCoverage} was produced using
174 * {link org.opengis.coverage.processing.GridCoverageProcessor} then it should return the
175 * source grid coverages of the one used as input to {@code GridCoverageProcessor}.
176 * In general this method is intended to return the original {@code GridCoverage}
177 * on which it depends.
178 *
179 * This is intended to allow applications to establish what {@code GridCoverage}s
180 * will be affected when others are updated, as well as to trace back to the "raw data".
181 *
182 * @return The sources data for a grid coverage.
183 */
184 List<GridCoverage> getSources();
185
186 /**
187 * Return a sequence of boolean values for a block.
188 * A value for each sample dimension will be returned.
189 * The semantic is the same as {@link #getDataBlock(GridRange, double[])}
190 * except for the return type.
191 *
192 * @param range Grid range for block of data to be accessed.
193 * @param destination An optionally preallocated array in which to store the values,
194 * or {@code null} if none.
195 * @return A sequence of boolean values for a given block in the coverage.
196 * If {@code destination} was non-null, then it is returned.
197 * Otherwise, a new array is allocated and returned.
198 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
199 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
200 * and too small to hold the output.
201 *
202 * @see #setDataBlock(GridRange, boolean[])
203 *
204 * @deprecated We should use some higher level construct instead (multi-dimensional array
205 * or something similar).
206 */
207 @Deprecated
208 @UML(identifier="getDataBlockAsBoolean", obligation=MANDATORY, specification=OGC_01004)
209 boolean[] getDataBlock(GridRange range, boolean[] destination)
210 throws InvalidRangeException, ArrayIndexOutOfBoundsException;
211
212 /**
213 * Return a sequence of 8 bits values for a block.
214 * A value for each sample dimension will be returned.
215 * The semantic is the same as {@link #getDataBlock(GridRange, double[])}
216 * except for the return type.
217 *
218 * @param range Grid range for block of data to be accessed.
219 * @param destination An optionally preallocated array in which to store the values,
220 * or {@code null} if none.
221 * @return A sequence of 8 bits values for a given block in the coverage.
222 * If {@code destination} was non-null, then it is returned.
223 * Otherwise, a new array is allocated and returned.
224 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
225 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
226 * and too small to hold the output.
227 *
228 * @see #setDataBlock(GridRange, byte[])
229 * @see javax.media.jai.UnpackedImageData#getByteData()
230 *
231 * @deprecated We should use some higher level construct instead (multi-dimensional array
232 * or something similar).
233 */
234 @Deprecated
235 @UML(identifier="getDataBlockAsByte", obligation=MANDATORY, specification=OGC_01004)
236 byte[] getDataBlock(GridRange range, byte[] destination)
237 throws InvalidRangeException, ArrayIndexOutOfBoundsException;
238
239 /**
240 * Return a sequence of 16 bits values for a block.
241 * A value for each sample dimension will be returned.
242 * The semantic is the same as {@link #getDataBlock(GridRange, double[])}
243 * except for the return type.
244 *
245 * @param range Grid range for block of data to be accessed.
246 * @param destination An optionally preallocated array in which to store the values,
247 * or {@code null} if none.
248 * @return A sequence of 16 bits values for a given block in the coverage.
249 * If {@code destination} was non-null, then it is returned.
250 * Otherwise, a new array is allocated and returned.
251 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
252 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
253 * and too small to hold the output.
254 *
255 * @see #setDataBlock(GridRange, int[])
256 * @see javax.media.jai.UnpackedImageData#getShortData()
257 *
258 * @deprecated We should use some higher level construct instead (multi-dimensional array
259 * or something similar).
260 */
261 @Deprecated
262 @UML(identifier="getDataBlockAsInteger", obligation=MANDATORY, specification=OGC_01004)
263 short[] getDataBlock(GridRange range, short[] destination)
264 throws InvalidRangeException, ArrayIndexOutOfBoundsException;
265
266 /**
267 * Return a sequence of 32 bits values for a block.
268 * A value for each sample dimension will be returned.
269 * The semantic is the same as {@link #getDataBlock(GridRange, double[])}
270 * except for the return type.
271 *
272 * @param range Grid range for block of data to be accessed.
273 * @param destination An optionally preallocated array in which to store the values,
274 * or {@code null} if none.
275 * @return A sequence of 32 bits values for a given block in the coverage.
276 * If {@code destination} was non-null, then it is returned.
277 * Otherwise, a new array is allocated and returned.
278 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
279 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
280 * and too small to hold the output.
281 *
282 * @see #setDataBlock(GridRange, int[])
283 * @see Raster#getPixels(int,int,int,int,int[])
284 * @see javax.media.jai.UnpackedImageData#getIntData()
285 *
286 * @deprecated We should use some higher level construct instead (multi-dimensional array
287 * or something similar).
288 */
289 @Deprecated
290 @UML(identifier="getDataBlockAsInteger", obligation=MANDATORY, specification=OGC_01004)
291 int[] getDataBlock(GridRange range, int[] destination)
292 throws InvalidRangeException, ArrayIndexOutOfBoundsException;
293
294 /**
295 * Return a sequence of float values for a block.
296 * A value for each sample dimension will be returned.
297 * The semantic is the same as {@link #getDataBlock(GridRange, double[])}
298 * except for the return type.
299 *
300 * @param range Grid range for block of data to be accessed.
301 * @param destination An optionally preallocated array in which to store the values,
302 * or {@code null} if none.
303 * @return A sequence of float values for a given block in the coverage.
304 * If {@code destination} was non-null, then it is returned.
305 * Otherwise, a new array is allocated and returned.
306 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
307 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
308 * and too small to hold the output.
309 *
310 * @see #setDataBlock(GridRange, float[])
311 * @see Raster#getPixels(int,int,int,int,float[])
312 * @see javax.media.jai.UnpackedImageData#getFloatData()
313 *
314 * @deprecated We should use some higher level construct instead (multi-dimensional array
315 * or something similar).
316 */
317 @Deprecated
318 float[] getDataBlock(GridRange range, float[] destination)
319 throws InvalidRangeException, ArrayIndexOutOfBoundsException;
320
321 /**
322 * Return a sequence of double values for a block.
323 * A value for each sample dimension will be returned.
324 *
325 * The return value is an <VAR>N</VAR>+1 dimensional safe-array, with dimensions
326 * (sample dimension, dimension <var>n</var>, dimension <var>n</var>-1, ... dimension 1).
327 *
328 * For 2 dimensional grid coverages, this safe array will be accessed as
329 * (sample dimension, column, row).
330 *
331 * The index values will be based from 0. The indices in the returned <VAR>N</VAR> dimensional
332 * safe array will need to be offset by {@code range} {@linkplain GridRange#getLower()
333 * minimum coordinates} to get equivalent grid coordinates.
334 * <p>
335 * The requested grid range must satisfy the following rules for each dimension of the grid
336 * coverage:
337 * <center>
338 * minimum grid coordinate <= {@linkplain GridRange#getLower() grid range mimimun} <=
339 * {@linkplain GridRange#getUpper() grid range maximum} <= maximum grid coordinate
340 * </center>
341 *
342 * The number of values returned will equal:
343 * <center>
344 * (max<sub>1</sub> - min<sub>1</sub> + 1) *
345 * (max<sub>2</sub> - min<sub>2</sub> + 1) ... *
346 * (max<sub>n</sub> - min<sub>n</sub> + 1) *
347 * {@link #getNumSampleDimensions numSampleDimensions}
348 * </center>
349 *
350 * Where <var>min</var> is the minimum ordinate in the grid range,
351 * <var>max</var> is the maximum ordinate in the grid range and
352 * <VAR>N</VAR> is the number of dimensions in the grid coverage.
353 *
354 * @departure integration
355 * OGC 01-004 defines this method as <code>getValueBlockAsDouble(GridRange)</code>.
356 * GeoAPI adds the <code>double[]</code> argument for reusing pre-allocated arrays,
357 * which is consistent with usage in <code>java.awt.image.Raster</code>.
358 *
359 * @param range Grid range for block of data to be accessed.
360 * @param destination An optionally preallocated array in which to store the values,
361 * or {@code null} if none.
362 * @return A sequence of double values for a given block in the coverage.
363 * If {@code destination} was non-null, then it is returned.
364 * Otherwise, a new array is allocated and returned.
365 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
366 * @throws ArrayIndexOutOfBoundsException if the {@code destination} array is not null
367 * and too small to hold the output.
368 *
369 * @rename Renamed {@code getValueBlockAsDouble} as {@code getDataBlockAsDouble}
370 * for consistency with all others {@code getDataBlock...} methods and
371 * {@code setDataBlockAsDouble}.
372 *
373 * @todo Which indices vary fastest?
374 *
375 * @see #setDataBlock(GridRange, double[])
376 * @see Raster#getPixels(int,int,int,int,double[])
377 * @see javax.media.jai.UnpackedImageData#getDoubleData()
378 *
379 * @deprecated We should use some higher level construct instead (multi-dimensional array
380 * or something similar).
381 */
382 @Deprecated
383 @UML(identifier="getValueBlockAsDouble", obligation=MANDATORY, specification=OGC_01004)
384 double[] getDataBlock(GridRange range, double[] destination)
385 throws InvalidRangeException, ArrayIndexOutOfBoundsException;
386
387 /**
388 * Return a block of grid coverage data for all sample dimensions.
389 * A value for each sample dimension will be returned.
390 * This operation provides efficient access of the grid values.
391 * The sequencing order of the values in the sequence will follow the rules
392 * given by {@code valueInBytePacking} and {@code bandPacking}
393 * defined in {@link GridPacking}.
394 *
395 * The requested grid range must satisfy the following rules for each dimension
396 * of the grid coverage:
397 *
398 * <center>
399 * minimum grid coordinate <= {@linkplain GridRange#getLower() grid range mimimun} <=
400 * {@linkplain GridRange#getUpper() grid range maximum} <= maximum grid coordinate
401 * </center>
402 *
403 * The sequence of bytes returned will match the data type of
404 * the dimension. For example, a grid with one 16 bit unsigned
405 * ({@link org.opengis.coverage.SampleDimensionType#UNSIGNED_16BITS UNSIGNED_16BITS})
406 * sample dimension will return 2 bytes for every cell in the block.
407 * <p>
408 * <strong>Byte padding rules for grid values of less than 8 bits</strong><br>
409 * For 2D grid coverages, padding is to the nearest byte for the following cases:
410 *
411 * <table cellpadding=6 border=0>
412 * <tr> <td>For PixelInterleaved</td>
413 * <td>For grids with multiple sample dimensions, padding occurs between
414 * pixels for each change in dimension type.</td>
415 * </tr>
416 * <tr> <td>For LineInterleaved</td>
417 * <td>Padding occurs at the end of each row or column (depending on the
418 * valueSequence of the grid).</td>
419 * </tr>
420 * <tr> <td>For BandSequencial</td>
421 * <td>Padding occurs at the end of every sample dimension.</td>
422 * </tr>
423 * </table>
424 *
425 * For grid values smaller than 8 bits, their order within each byte is given by the
426 * value defined in {@link GridPacking#getValueInBytePacking valueInBytePacking}.
427 * For grid values bigger than 8 bits, the order of their bytes is given by the
428 * value defined in {@link GridPacking#getByteInValuePacking byteInValuePacking}.
429 *
430 * @param range Grid range for block of data to be accessed.
431 * @return a block of grid coverage data for all sample dimensions.
432 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
433 *
434 * @todo This operation can't be implemented efficiently in Java with a {@code byte[]}
435 * return type, since there is no way to cast an array of arbitrary type to an array
436 * of type {@code byte[]}. Even the {@code java.nio.Buffer} doesnt allow
437 * that (it allows the opposite way however).
438 *
439 * @deprecated We should use some higher level construct instead (multi-dimensional array
440 * or something similar).
441 */
442 @Deprecated
443 @UML(identifier="getPackedDataBlock", obligation=MANDATORY, specification=OGC_01004)
444 byte[] getPackedDataBlock(GridRange range) throws InvalidRangeException;
445
446 /**
447 * Set a block of boolean values for all sample dimensions.
448 * The semantic is the same as {@link #setDataBlock(GridRange, double[])}.
449 *
450 * @param range Grid range for block of data to be accessed.
451 * @param values Sequence of grid values for the given region.
452 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
453 * @throws GridNotEditableException if the grid coverage is not {@linkplain #isDataEditable editable}.
454 * @throws ArrayIndexOutOfBoundsException if the {@code values} array is too small.
455 *
456 * @see #isDataEditable
457 * @see #getDataBlock(GridRange, boolean[])
458 *
459 * @deprecated We should use some higher level construct instead (multi-dimensional array
460 * or something similar).
461 */
462 @Deprecated
463 @UML(identifier="setDataBlockAsBoolean", obligation=MANDATORY, specification=OGC_01004)
464 void setDataBlock(GridRange range, boolean[] values)
465 throws InvalidRangeException, GridNotEditableException, ArrayIndexOutOfBoundsException;
466
467 /**
468 * Set a block of 8 bits values for all sample dimensions.
469 * The semantic is the same as {@link #setDataBlock(GridRange, double[])}.
470 *
471 * @param range Grid range for block of data to be accessed.
472 * @param values Sequence of grid values for the given region.
473 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
474 * @throws GridNotEditableException if the grid coverage is not {@linkplain #isDataEditable editable}.
475 * @throws ArrayIndexOutOfBoundsException if the {@code values} array is too small.
476 *
477 * @see #isDataEditable
478 * @see #getDataBlock(GridRange, byte[])
479 *
480 * @deprecated We should use some higher level construct instead (multi-dimensional array
481 * or something similar).
482 */
483 @Deprecated
484 @UML(identifier="setDataBlockAsByte", obligation=MANDATORY, specification=OGC_01004)
485 void setDataBlock(GridRange range, byte[] values)
486 throws InvalidRangeException, GridNotEditableException, ArrayIndexOutOfBoundsException;
487
488 /**
489 * Set a block of 16 bits values for all sample dimensions.
490 * The semantic is the same as {@link #setDataBlock(GridRange, double[])}.
491 *
492 * @param range Grid range for block of data to be accessed.
493 * @param values Sequence of grid values for the given region.
494 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
495 * @throws GridNotEditableException if the grid coverage is not {@linkplain #isDataEditable editable}.
496 * @throws ArrayIndexOutOfBoundsException if the {@code values} array is too small.
497 *
498 * @see #isDataEditable
499 * @see #getDataBlock(GridRange, short[])
500 *
501 * @deprecated We should use some higher level construct instead (multi-dimensional array
502 * or something similar).
503 */
504 @Deprecated
505 @UML(identifier="setDataBlockAsByte", obligation=MANDATORY, specification=OGC_01004)
506 void setDataBlock(GridRange range, short[] values)
507 throws InvalidRangeException, GridNotEditableException, ArrayIndexOutOfBoundsException;
508
509 /**
510 * Set a block of 32 bits values for all sample dimensions.
511 * The semantic is the same as {@link #setDataBlock(GridRange, double[])}.
512 *
513 * @param range Grid range for block of data to be accessed.
514 * @param values Sequence of grid values for the given region.
515 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
516 * @throws GridNotEditableException if the grid coverage is not {@linkplain #isDataEditable editable}.
517 * @throws ArrayIndexOutOfBoundsException if the {@code values} array is too small.
518 *
519 * @see #isDataEditable
520 * @see #getDataBlock(GridRange, int[])
521 * @see WritableRaster#setPixels(int,int,int,int,int[])
522 *
523 * @deprecated We should use some higher level construct instead (multi-dimensional array
524 * or something similar).
525 */
526 @Deprecated
527 @UML(identifier="setDataBlockAsInteger", obligation=MANDATORY, specification=OGC_01004)
528 void setDataBlock(GridRange range, int[] values)
529 throws InvalidRangeException, GridNotEditableException, ArrayIndexOutOfBoundsException;
530
531 /**
532 * Set a block of float values for all sample dimensions.
533 * The semantic is the same as {@link #setDataBlock(GridRange, double[])}.
534 *
535 * @param range Grid range for block of data to be accessed.
536 * @param values Sequence of grid values for the given region.
537 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
538 * @throws GridNotEditableException if the grid coverage is not {@linkplain #isDataEditable editable}.
539 * @throws ArrayIndexOutOfBoundsException if the {@code values} array is too small.
540 *
541 * @see #isDataEditable
542 * @see #getDataBlock(GridRange, float[])
543 * @see WritableRaster#setPixels(int,int,int,int,float[])
544 *
545 * @deprecated We should use some higher level construct instead (multi-dimensional array
546 * or something similar).
547 */
548 @Deprecated
549 @UML(identifier="setDataBlockAsInteger", obligation=MANDATORY, specification=OGC_01004)
550 void setDataBlock(GridRange range, float[] values)
551 throws InvalidRangeException, GridNotEditableException, ArrayIndexOutOfBoundsException;
552
553 /**
554 * Set a block of double values for all sample dimensions.
555 * The requested grid range must satisfy the following rules for each
556 * dimension of the grid coverage:
557 *
558 * <center>
559 * minimum grid coordinate <= {@linkplain GridRange#getLower() grid range mimimun} <=
560 * {@linkplain GridRange#getUpper() grid range maximum} <= maximum grid coordinate
561 * </center>
562 *
563 * The number of values must equal:
564 *
565 * <center>
566 * (max<sub>1</sub> - min<sub>1</sub> + 1) *
567 * (max<sub>2</sub> - min<sub>2</sub> + 1) ... *
568 * (max<sub>n</sub> - min<sub>n</sub> + 1) *
569 * {@link #getNumSampleDimensions numSampleDimensions}
570 * </center>
571 *
572 * Where <var>min</var> is the minimum ordinate in the grid range,
573 * <var>max</var> is the maximum ordinate in the grid range and
574 * <VAR>N</VAR> is the number of dimensions in the grid coverage.
575 *
576 * @param range Grid range for block of data to be accessed.
577 * @param values Sequence of grid values for the given region.
578 * @throws InvalidRangeException if {@code range} is out of this grid range bounds.
579 * @throws GridNotEditableException if the grid coverage is not {@linkplain #isDataEditable editable}.
580 * @throws ArrayIndexOutOfBoundsException if the {@code values} array is too small.
581 *
582 * @see #isDataEditable
583 * @see #getDataBlock(GridRange, double[])
584 * @see WritableRaster#setPixels(int,int,int,int,double[])
585 *
586 * @deprecated We should use some higher level construct instead (multi-dimensional array
587 * or something similar).
588 */
589 @Deprecated
590 @UML(identifier="setDataBlockAsDouble", obligation=MANDATORY, specification=OGC_01004)
591 void setDataBlock(GridRange range, double[] values)
592 throws InvalidRangeException, GridNotEditableException, ArrayIndexOutOfBoundsException;
593 }