/
ThumbnailStore.java
365 lines (346 loc) · 15.5 KB
/
ThumbnailStore.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
/*
* $Id$
*
* Copyright 2006 University of Dundee. All rights reserved.
* Use is subject to license terms supplied in LICENSE.txt
*/
package ome.api;
import java.util.Map;
import java.util.Set;
import ome.annotations.NotNull;
import ome.annotations.Validate;
/**
* Provides methods for dealing with thumbnails. Provision is provided to
* retrieve thumbnails using the on-disk cache (provided by <i>ROMIO</i>) or on
* the fly.
* <p>
* NOTE: The calling order for the service is as follows:
* <ol>
* <li>setPixelsId()</li>
* <li>any of the thumbnail accessor methods or resetDefaults()</li>
* </ol>
* </p>
*
* @author Chris Allan <a
* href="mailto:callan@blackcat.ca">callan@blackcat.ca</a>
* @version 3.0
* @since 3.0
*/
public interface ThumbnailStore extends StatefulServiceInterface {
/**
* This method manages the state of the service; it must be invoked before
* using any other methods. As the <pre>ThumbnailStore</pre> relies on the
* <pre>RenderingEngine</pre>, a valid rendering definition must be
* available for it to work.
*
* @param pixelsId
* an {@link ome.model.core.Pixels} id.
* @throws ApiUsageException
* if no pixels object exists with the ID <i>pixelsId</i>.
* @return <code>true</code> if a <code>RenderingDef</code> exists for the
* <code>Pixels</code> set, otherwise <code>false</code>
*
*/
public boolean setPixelsId(long pixelsId);
/**
* This returns the last available <i>in progress</i> state for a
* thumbnail. Its return value is <b>only</b> expected to be valid after
* the call to any of the individual thumbnail retrieval methods.
* @return <code>true</code> if the image is in the process of being
* imported or a pyramid is being generated for it.
*
*/
public boolean isInProgress();
/**
* This method manages the state of the service; it should be invoked
* directly after {@link #setPixelsId(long)}. If it is not invoked with a
* valid rendering definition ID before using the thumbnail accessor
* methods execution continues as if <i>renderingDefId</i> were set to
* <code>null</code>.
*
* @param renderingDefId
* an {@link ome.model.display.RenderingDef} id.
* <code>null</code> specifies the user's currently active
* rendering settings to be used.
* @throws ValidationException
* if no rendering definition exists with the ID
* <i>renderingDefId</i>.
*/
public void setRenderingDefId(long renderingDefId);
/**
* Return the id of the {@link ome.model.display.RenderingDef} loaded in
* this instance.
*/
public long getRenderingDefId();
/**
* Retrieves a thumbnail for a pixels set using a given set of rendering
* settings (RenderingDef). If the thumbnail exists in the on-disk cache
* it will be returned directly, otherwise it will be created as in
* {@link #getThumbnailDirect(Integer, Integer)}, placed in the on-disk
* cache and returned.
*
* @param sizeX
* the X-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @param sizeY
* the Y-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>sizeX</i> > pixels.sizeX</li>
* <li><i>sizeX</i> is negative</li>
* <li><i>sizeY</i> > pixels.sizeY</li>
* <li><i>sizeY</i> is negative</li>
* <li>{@link #setPixelsId(long)} has not yet been called</li>
* </ul>
* @return a JPEG thumbnail byte buffer.
* @see #getThumbnailDirect(Integer, Integer)
*/
public byte[] getThumbnail(Integer sizeX, Integer sizeY);
/**
* Retrieves a number of thumbnails for pixels sets using given sets of
* rendering settings (RenderingDef). If the thumbnails exist in the
* on-disk cache they will be returned directly, otherwise they will be
* created as in {@link #getThumbnailDirect(Integer, Integer)}, placed in
* the on-disk cache and returned. Unlike the other thumbnail retrieval
* methods, this method <b>may</b> be called without first calling
* {@link #setPixelsId(long)}.
*
* @param sizeX
* the X-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @param sizeY
* the Y-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @param pixelsIds the Pixels sets to retrieve thumbnails for.
* @return a {@link Map} whose keys are pixels ids and values are JPEG
* thumbnail byte buffers or <code>null</code> if an exception was thrown
* while attempting to retrieve the thumbnail for that particular Pixels
* set.
* @see #getThumbnail(Integer, Integer)
*/
public Map<Long, byte[]> getThumbnailSet(Integer sizeX, Integer sizeY,
@NotNull @Validate(Long.class) Set<Long> pixelsIds);
/**
* Retrieves a number of thumbnails for pixels sets using given sets of
* rendering settings (RenderingDef). If the Thumbnails exist in the
* on-disk cache they will be returned directly, otherwise they will be
* created as in {@link #getThumbnailByLongestSideDirect}. The longest
* side of the image will be used to calculate the size for the smaller
* side in order to keep the aspect ratio of the original image. Unlike the
* other thumbnail retrieval methods, this method <b>may</b> be called
* without first calling {@link #setPixelsId(long)}.
*
* @param size
* the size of the longest side of the thumbnail requested.
* <code>null</code> specifies the default size of 48.
* @param pixelsIds the Pixels sets to retrieve thumbnails for.
* @return a {@link Map} whose keys are pixels ids and values are JPEG
* thumbnail byte buffers or <code>null</code> if an exception was thrown
* while attempting to retrieve the thumbnail for that particular Pixels
* set.
* @see #getThumbnailSet(Integer, Integer, Set)
*/
public Map<Long, byte[]> getThumbnailByLongestSideSet(Integer size,
@NotNull @Validate(Long.class) Set<Long> pixelsIds);
/**
* Retrieves a thumbnail for a pixels set using a given set of rendering
* settings (RenderingDef). If the thumbnail exists in the on-disk cache it
* will bereturned directly, otherwise it will be created as in
* {@link #getThumbnailDirect(Integer, Integer)}, placed in the on-disk
* cache and returned. The longest side of the image will be used to
* calculate the size for the smaller side in order to keep the aspect
* ratio of the original image.
*
* @param size
* the size of the longest side of the thumbnail requested.
* <code>null</code> specifies the default size of 48.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>size</i> > pixels.sizeX and pixels.sizeY</li>
* <li>{@link #setPixelsId(long)} has not yet been called</li>
* </ul>
* @return a JPEG thumbnail byte buffer.
* @see #getThumbnail(Integer, Integer)
*/
public byte[] getThumbnailByLongestSide(Integer size);
/**
* Retrieves a thumbnail for a pixels set using a given set of rendering
* settings (RenderingDef). The Thumbnail will always be created directly,
* ignoring the on-disk cache.
*
* @param sizeX
* the X-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @param sizeY
* the Y-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>sizeX</i> > pixels.sizeX</li>
* <li><i>sizeX</i> is negative</li>
* <li><i>sizeY</i> > pixels.sizeY</li>
* <li><i>sizeY</i> is negative</li>
* <li>{@link #setPixelsId(long)} has not yet been called</li>
* </ul>
* @return a JPEG thumbnail byte buffer.
* @see #getThumbnail(Integer, Integer)
*/
public byte[] getThumbnailDirect(Integer sizeX, Integer sizeY);
/**
* Retrieves a thumbnail for a pixels set using a given set of rendering
* settings (RenderingDef) for a particular section. The Thumbnail will
* always be created directly, ignoring the on-disk cache.
*
* @param theZ the optical section (offset across the Z-axis) to use.
* @param theT the timepoint (offset across the T-axis) to use.
* @param sizeX
* the X-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @param sizeY
* the Y-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>sizeX</i> > pixels.sizeX</li>
* <li><i>sizeX</i> is negative</li>
* <li><i>sizeY</i> > pixels.sizeY</li>
* <li><i>sizeY</i> is negative</li>
* <li><i>theZ</i> is out of range</li>
* <li><i>theT</i> is out of range</li>
* <li>{@link #setPixelsId(long)} has not yet been called</li>
* </ul>
* @return a JPEG thumbnail byte buffer.
* @see #getThumbnail(Integer, Integer)
*/
public byte[] getThumbnailForSectionDirect(int theZ, int theT,
Integer sizeX, Integer sizeY);
/**
* Retrieves a thumbnail for a pixels set using a given set of rendering
* settings (RenderingDef). The Thumbnail will always be created directly,
* ignoring the on-disk cache. The longest side of the image will be used to
* calculate the size for the smaller side in order to keep the aspect ratio
* of the original image.
*
* @param size
* the size of the longest side of the thumbnail requested.
* <code>null</code> specifies the default size of 48.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>size</i> > pixels.sizeX and pixels.sizeY</li>
* <li>{@link #setPixelsId(long)} has not yet been called</li>
* </ul>
* @return a JPEG thumbnail byte buffer.
* @see #getThumbnailDirect(Integer, Integer)
*/
public byte[] getThumbnailByLongestSideDirect(Integer size);
/**
* Retrieves a thumbnail for a pixels set using a given set of rendering
* settings (RenderingDef) for a particular section. The Thumbnail will
* always be created directly, ignoring the on-disk cache. The longest side
* of the image will be used to calculate the size for the smaller side in
* order to keep the aspect ratio of the original image.
*
* @param theZ the optical section (offset across the Z-axis) to use.
* @param theT the timepoint (offset across the T-axis) to use.
* @param size
* the size of the longest side of the thumbnail requested.
* <code>null</code> specifies the default size of 48.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>size</i> > pixels.sizeX and pixels.sizeY</li>
* <li>{@link #setPixelsId(long)} has not yet been called</li>
* </ul>
* @return a JPEG thumbnail byte buffer.
* @see #getThumbnailDirect(Integer, Integer)
*/
public byte[] getThumbnailForSectionByLongestSideDirect(int theZ, int theT,
Integer size);
/**
* Creates a thumbnail for a pixels set using a given set of rendering
* settings (RenderingDef) in the on-disk cache.
*
* @param sizeX
* the X-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @param sizeY
* the Y-axis width of the thumbnail. <code>null</code>
* specifies the default size of 48.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>sizeX</i> > pixels.sizeX</li>
* <li><i>sizeX</i> is negative</li>
* <li><i>sizeY</i> > pixels.sizeY</li>
* <li><i>sizeY</i> is negative</li>
* <li>{@link #setPixelsId(long)} has not yet been called</li>
* </ul>
* @see #getThumbnail(Integer, Integer)
* @see #getThumbnailDirect(Integer, Integer)
*/
public void createThumbnail(Integer sizeX, Integer sizeY);
/**
* Creates thumbnails for a number of pixels sets using a given set of
* rendering settings (RenderingDef) in the on-disk cache. Unlike the
* other thumbnail creation methods, this method <b>may</b> be called
* without first calling {@link #setPixelsId(long)}. This method <b>will not</b>
* reset or modify rendering settings in any way. If rendering settings for
* a pixels set are not present, thumbnail creation for that pixels set
* <b>will not</b> be performed.
*
* @param size
* the size of the longest side of the thumbnail requested.
* <code>null</code> specifies the default size of 48.
* @param pixelsIds the Pixels sets to retrieve thumbnails for.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>size</i> > pixels.sizeX and pixels.sizeY</li>
* <li><i>size</i> is negative</li>
* </ul>
* @see #createThumbnail(Integer, Integer)
* @see #createThumbnails()
*/
public void createThumbnailsByLongestSideSet(Integer size,
@NotNull @Validate(Long.class) Set<Long> pixelsIds);
/**
* Creates thumbnails for a pixels set using a given set of rendering
* settings (RenderingDef) in the on-disk cache for <b>every</b>
* sizeX/sizeY combination already cached.
*
* @see #getThumbnail(Integer, Integer)
* @see #getThumbnailDirect(Integer, Integer)
*/
public void createThumbnails();
/**
* Checks if a thumbnail of a particular size exists for a pixels set.
*
* @param sizeX
* the X-axis width of the thumbnail. <code>null</code>
* specifies use the default size of 48.
* @param sizeY
* the Y-axis width of the thumbnail. <code>null</code>
* specifies user the default size of 48.
* @throws ApiUsageException
* if:
* <ul>
* <li><i>sizeX</i> is negative</li>
* <li><i>sizeY</i> is negative</li>
* <li>{@link #setPixelsId(long)} has not yet been called</li>
* </ul>
* @see #getThumbnail(Integer, Integer)
* @see #getThumbnailDirect(Integer, Integer)
*/
public boolean thumbnailExists(Integer sizeX, Integer sizeY);
/**
* Resets the rendering definition for the active pixels set to its
* default settings.
*/
public void resetDefaults();
}