1 package nom.tam.fits.compression.algorithm.api;
2
3 import nom.tam.fits.compression.provider.param.api.ICompressParameters;
4
5 /*
6 * #%L
7 * nom.tam FITS library
8 * %%
9 * Copyright (C) 1996 - 2024 nom-tam-fits
10 * %%
11 * This is free and unencumbered software released into the public domain.
12 *
13 * Anyone is free to copy, modify, publish, use, compile, sell, or
14 * distribute this software, either in source code form or as a compiled
15 * binary, for any purpose, commercial or non-commercial, and by any
16 * means.
17 *
18 * In jurisdictions that recognize copyright laws, the author or authors
19 * of this software dedicate any and all copyright interest in the
20 * software to the public domain. We make this dedication for the benefit
21 * of the public at large and to the detriment of our heirs and
22 * successors. We intend this dedication to be an overt act of
23 * relinquishment in perpetuity of all present and future rights to this
24 * software under copyright law.
25 *
26 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
27 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
28 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
29 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
30 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
31 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
32 * OTHER DEALINGS IN THE SOFTWARE.
33 * #L%
34 */
35
36 /**
37 * Option for the compression algorithm, implementors are used to control the compression algorithm.
38 */
39 public interface ICompressOption extends Cloneable {
40
41 /**
42 * Returns an independent copy of this option. Modifications to the original or the copy will not affect the other.
43 *
44 * @return copy the option (normally the option from with the copy happened is saved as original).
45 */
46 ICompressOption copy();
47
48 /**
49 * (<i>for internal use</i>) Returns the parameters that represent the settings for this option in the FITS header
50 * or compressed data column.
51 *
52 * @return the parameters that must be synchronized with the hdu meta data.
53 *
54 * @see #setParameters(ICompressParameters)
55 */
56 ICompressParameters getCompressionParameters();
57
58 /**
59 * Checks if this type of compression is inherently lossy
60 *
61 * @return <code>true</code> if the compression done with this specified options uses approximations. That means if
62 * the reconstruction of the data is excact the return should be <code>false</code>.
63 */
64 boolean isLossyCompression();
65
66 /**
67 * (<i>for internal use</i>) Sets the parameters that link the options to how they are recorded in the FITS headers
68 * or compressed table columns.
69 *
70 * @param parameters the parameters to synchronized
71 *
72 * @see #getCompressionParameters()
73 */
74 void setParameters(ICompressParameters parameters);
75
76 /**
77 * Set the tile height (if the option supports it). If the implementing option class does not have a setting for
78 * tile size, it should simply ignore the setting and return normally.
79 *
80 * @param value the new tile height in pixels
81 *
82 * @return itself
83 *
84 * @see #getTileHeight()
85 * @see #setTileWidth(int)
86 */
87 ICompressOption setTileHeight(int value);
88
89 /**
90 * Set the tile width (if the option supports it). If the implementing option class does not have a setting for tile
91 * size, it should simply ignore the setting and return normally.
92 *
93 * @param value the new tile with in pixels
94 *
95 * @return itself
96 *
97 * @see #getTileWidth()
98 * @see #setTileHeight(int)
99 */
100 ICompressOption setTileWidth(int value);
101
102 /**
103 * Returns the tile height (if supported), or else 0 (also the default implementation).
104 *
105 * @return the tile height in pixels, or 0 if the options do not have a tile size setting.
106 *
107 * @see #setTileHeight(int)
108 * @see #getTileWidth()
109 *
110 * @since 1.18
111 */
112 default int getTileHeight() {
113 return 0;
114 }
115
116 /**
117 * Returns the tile width (if supported), or else 0 (also the default implementation).
118 *
119 * @return the tile width in pixels, or 0 if the options do not have a tile size setting.
120 *
121 * @see #setTileHeight(int)
122 * @see #getTileWidth()
123 *
124 * @since 1.18
125 */
126 default int getTileWidth() {
127 return 0;
128 }
129
130 /**
131 * (<i>for internal use</i>) Recasts these options for the specific implementation class
132 *
133 * @param clazz the implementation class
134 * @param <T> these options recast to the designated implementation type.
135 *
136 * @return the recast version of us or <code>null</code> if the recasting is not available for the specified
137 * class type.
138 */
139 <T> T unwrap(Class<T> clazz);
140 }