1 /*
2 * To change this template, choose Tools | Templates
3 * and open the template in the editor.
4 */
5 package nom.tam.image;
6
7 /*
8 * #%L
9 * nom.tam FITS library
10 * %%
11 * Copyright (C) 2004 - 2024 nom-tam-fits
12 * %%
13 * This is free and unencumbered software released into the public domain.
14 *
15 * Anyone is free to copy, modify, publish, use, compile, sell, or
16 * distribute this software, either in source code form or as a compiled
17 * binary, for any purpose, commercial or non-commercial, and by any
18 * means.
19 *
20 * In jurisdictions that recognize copyright laws, the author or authors
21 * of this software dedicate any and all copyright interest in the
22 * software to the public domain. We make this dedication for the benefit
23 * of the public at large and to the detriment of our heirs and
24 * successors. We intend this dedication to be an overt act of
25 * relinquishment in perpetuity of all present and future rights to this
26 * software under copyright law.
27 *
28 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
29 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
30 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
31 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
32 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
33 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
34 * OTHER DEALINGS IN THE SOFTWARE.
35 * #L%
36 */
37
38 import java.io.IOException;
39
40 /**
41 * Image tiling interface. This interface supports general multi-dimensional tiling. However, FITS tiles are always
42 * 2-dimentional, but really images of any dimensions may be covered with 2D tiles.
43 *
44 * @author tmcglynn
45 */
46 public interface ImageTiler {
47
48 /**
49 * Returns the entire image reconstructed from the available tiles.
50 *
51 * @return the complete reconstructed image from the available tiles, as a Java array. This may be an
52 * array of promitives (such as <code>float[][]</code>) for images, or an
53 * <code>Object[]</code> for binary tables.
54 *
55 * @throws IOException if there was an error accessing the tile data from the input.
56 *
57 * @see #getTile(int[], int[])
58 */
59 Object getCompleteImage() throws IOException;
60
61 /**
62 * Returns a tile from the image of the specified size at the specified location. An image tile is returned as a
63 * one-dimensional array although the image will normally be multidimensional.
64 *
65 * @param start the pixels indices where the tile starts in the full image. The array =hould contain a value
66 * for each image dimension.
67 * @param lengths the tile size in pixels. The array should contain a value for each image dimension. For the
68 * supported 2D tiles, the values beyond the first two entries should be set to 1.
69 *
70 * @return a Java array containing data for the requested tile. This will always be a flattened 1D
71 * array, even if the image is multidimensional
72 *
73 * @throws IOException if there was an error accessing the tile data from the input.
74 *
75 * @see #getTile(Object, int[], int[])
76 * @see #getTile(int[], int[], int[])
77 * @see #getCompleteImage()
78 */
79 Object getTile(int[] start, int[] lengths) throws IOException;
80
81 /**
82 * Returns a sparsely sampled tile from the image of the specified size at the specified location.
83 *
84 * @param start the pixels indices where the tile starts in the full image. The array =hould contain a value
85 * for each image dimension.
86 * @param lengths the tile size in pixels. The array should contain a value for each image dimension. For the
87 * supported 2D tiles, the values beyond the first two entries should be set to 1.
88 * @param steps the sampling frequency of the original image, in pixels. The array =hould contain a value for
89 * each image dimension.
90 *
91 * @return a Java array containing data for the requested tile. This will always be a flattened 1D
92 * array, even if the image is multidimensional
93 *
94 * @throws IOException if there was an error accessing the tile data from the input.
95 *
96 * @see #getTile(Object, int[], int[], int[])
97 * @see #getTile(int[], int[])
98 * @see #getCompleteImage()
99 */
100 default Object getTile(int[] start, int[] lengths, int[] steps) throws IOException {
101 throw new UnsupportedOperationException("Striding feature not yet implemented.");
102 }
103
104 /**
105 * Fills the supplied array or output stream with the data from an image tile of the specified size at the specified
106 * location.
107 *
108 * @param output A one-dimensional output array or stream. Data not within the valid limits of the image will
109 * be left unchanged. For an array, the length should be the product of lengths. Optionally
110 * provide an {@link nom.tam.util.ArrayDataOutput} to stream out data and not fill memory;
111 * useful for web applications.
112 * @param start the pixels indices where the tile starts in the full image. The array =hould contain a value
113 * for each image dimension.
114 * @param lengths the tile size in pixels. The array =hould contain a value for each image dimension. For the
115 * supported 2D tiles, the values beyond the first two entries should be set to 1.
116 *
117 * @throws IOException if there was an error writing the tile to the output.
118 *
119 * @see #getTile(Object, int[], int[])
120 * @see #getTile(int[], int[], int[])
121 * @see #getCompleteImage()
122 */
123 void getTile(Object output, int[] start, int[] lengths) throws IOException;
124
125 /**
126 * Fills the supplied array our output stream with the sparsely sampled data from an image tile of the specified
127 * size at the specified location.
128 *
129 * @param output A one-dimensional output array or stream. Data not within the valid limits of the image will
130 * be left unchanged. For an array, the length should be the product of lengths. Optionally
131 * provide an {@link nom.tam.util.ArrayDataOutput} to stream out data and not fill memory;
132 * useful for web applications.
133 * @param start the pixels indices where the tile starts in the full image. The array =hould contain a value
134 * for each image dimension.
135 * @param lengths the tile size in pixels. The array =hould contain a value for each image dimension. For the
136 * supported 2D tiles, the values beyond the first two entries should be set to 1.
137 * @param steps the sampling frequency of the original image, in pixels. The array =hould contain a value for
138 * each image dimension.
139 *
140 * @throws IOException if there was an error writing the tile to the output.
141 *
142 * @see #getTile(Object, int[], int[])
143 * @see #getTile(int[], int[], int[])
144 * @see #getCompleteImage()
145 */
146 default void getTile(Object output, int[] start, int[] lengths, int[] steps) throws IOException {
147 throw new UnsupportedOperationException("Striding feature not yet implemented.");
148 }
149 }