001/*****************************************************************************
002 * Copyright by The HDF Group.                                               *
003 * Copyright by the Board of Trustees of the University of Illinois.         *
004 * All rights reserved.                                                      *
005 *                                                                           *
006 * This file is part of the HDF Java Products distribution.                  *
007 * The full copyright notice, including terms governing use, modification,   *
008 * and redistribution, is contained in the files COPYING and Copyright.html. *
009 * COPYING can be found at the root of the source code distribution tree.    *
010 * Or, see https://support.hdfgroup.org/products/licenses.html               *
011 * If you do not have access to either file, you may request a copy from     *
012 * help@hdfgroup.org.                                                        *
013 ****************************************************************************/
014
015package hdf.object;
016
017import java.util.Iterator;
018import java.util.List;
019import java.util.Vector;
020
021/**
022 * A scalar dataset is a multiple dimension array of scalar points. The Datatype of a scalar dataset must be an atomic
023 * datatype. Common datatypes of scalar datasets include char, byte, short, int, long, float, double and string.
024 * <p>
025 * A ScalarDS can be an image or spreadsheet data. ScalarDS defines methods to deal with both images and
026 * spreadsheets.
027 * <p>
028 * ScalarDS is an abstract class. Current implementing classes are the H4SDS, H5GRImage and H5ScalarDS.
029 *
030 * @version 1.1 9/4/2007
031 * @author Peter X. Cao
032 */
033public abstract class ScalarDS extends Dataset {
034    private static final long serialVersionUID = 8925371455928203981L;
035
036    private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(ScalarDS.class);
037
038    /************************************************************
039     * The following constant strings are copied from           *
040     * https://support.hdfgroup.org/HDF5/doc/ADGuide/ImageSpec.html *
041     * to make the definition consistent with the image specs.  *
042     ************************************************************/
043
044    /**
045     * Indicates that the pixel RGB values are contiguous.
046     */
047    public static final int INTERLACE_PIXEL = 0;
048
049    /** Indicates that each pixel component of RGB is stored as a scan line. */
050    public static final int INTERLACE_LINE = 1;
051
052    /** Indicates that each pixel component of RGB is stored as a plane. */
053    public static final int INTERLACE_PLANE = 2;
054
055    /**
056     * The interlace mode of the stored raster image data. Valid values are INTERLACE_PIXEL, INTERLACE_LINE and
057     * INTERLACE_PLANE.
058     */
059    protected int interlace;
060
061    /**
062     * The min-max range of image data values. For example, [0, 255] indicates the min is 0, and the max is 255.
063     */
064    protected double[] imageDataRange;
065
066    /**
067     * The indexed RGB color model with 256 colors.
068     * <p>
069     * The palette values are stored in a two-dimensional byte array and arrange by color components of red, green and
070     * blue. palette[][] = byte[3][256], where, palette[0][], palette[1][] and palette[2][] are the red, green and blue
071     * components respectively.
072     */
073    protected byte[][] palette;
074
075    /**
076     * True if this dataset is an image.
077     */
078    protected boolean isImage;
079
080    /**
081     * True if this dataset is a true color image.
082     */
083    protected boolean isTrueColor;
084
085    /**
086     * True if this dataset is ASCII text.
087     */
088    protected boolean isText;
089
090    /**
091     * Flag to indicate is the original unsigned C data is converted.
092     */
093    protected boolean unsignedConverted;
094
095    /** The fill value of the dataset. */
096    protected Object fillValue = null;
097
098    private List<Number> filteredImageValues;
099
100    /** Flag to indicate if the dataset is displayed as an image. */
101    protected boolean isImageDisplay;
102
103    /**
104     * Flag to indicate if the dataset is displayed as an image with default order of dimensions.
105     */
106    protected boolean isDefaultImageOrder;
107
108    /**
109     * Flag to indicate if the FillValue is converted from unsigned C.
110     */
111    public boolean isFillValueConverted;
112
113    /**
114     * Constructs an instance of a ScalarDS with specific name and path. An HDF data object must have a name. The path
115     * is the group path starting from the root.
116     * <p>
117     * For example, in H5ScalarDS(h5file, "dset", "/arrays/"), "dset" is the name of the dataset, "/arrays" is the group
118     * path of the dataset.
119     *
120     * @param theFile
121     *            the file that contains the data object.
122     * @param theName
123     *            the name of the data object, e.g. "dset".
124     * @param thePath
125     *            the full path of the data object, e.g. "/arrays/".
126     */
127    public ScalarDS(FileFormat theFile, String theName, String thePath) {
128        this(theFile, theName, thePath, null);
129    }
130
131    /**
132     * @deprecated Not for public use in the future.<br>
133     *             Using {@link #ScalarDS(FileFormat, String, String)}
134     *
135     * @param theFile
136     *            the file that contains the data object.
137     * @param theName
138     *            the name of the data object, e.g. "dset".
139     * @param thePath
140     *            the full path of the data object, e.g. "/arrays/".
141     * @param oid
142     *            the v of the data object.
143     */
144    @Deprecated
145    public ScalarDS(FileFormat theFile, String theName, String thePath, long[] oid) {
146        super(theFile, theName, thePath, oid);
147
148        palette = null;
149        isImage = false;
150        isTrueColor = false;
151        isText = false;
152        interlace = -1;
153        imageDataRange = null;
154        isImageDisplay = false;
155        isDefaultImageOrder = true;
156        isFillValueConverted = false;
157        filteredImageValues = new Vector<>();
158    }
159
160    /*
161     * (non-Javadoc)
162     *
163     * @see hdf.object.Dataset#clearData()
164     */
165    @Override
166    public void clearData() {
167        super.clearData();
168        unsignedConverted = false;
169    }
170
171    /**
172     * Converts the data values of this dataset to appropriate Java integer if they are unsigned integers.
173     *
174     * @see hdf.object.Dataset#convertToUnsignedC(Object)
175     * @see hdf.object.Dataset#convertFromUnsignedC(Object, Object)
176     *
177     * @return the converted data buffer.
178     */
179    @Override
180    public Object convertFromUnsignedC() {
181        log.trace("convertFromUnsignedC(): start");
182        // keep a copy of original buffer and the converted buffer
183        // so that they can be reused later to save memory
184        log.trace("convertFromUnsignedC(): unsigned={}", getDatatype().isUnsigned());
185        if ((data != null) && getDatatype().isUnsigned() && !unsignedConverted) {
186            log.trace("convertFromUnsignedC(): convert");
187            originalBuf = data;
188            convertedBuf = convertFromUnsignedC(originalBuf, convertedBuf);
189            data = convertedBuf;
190            unsignedConverted = true;
191
192            if (fillValue != null) {
193                if (!isFillValueConverted) {
194                    fillValue = convertFromUnsignedC(fillValue, null);
195                    isFillValueConverted = true;
196                }
197            }
198        }
199
200        log.trace("convertFromUnsignedC(): finish");
201        return data;
202    }
203
204    /**
205     * Converts Java integer data of this dataset back to unsigned C-type integer data if they are unsigned integers.
206     *
207     * @see hdf.object.Dataset#convertToUnsignedC(Object)
208     * @see hdf.object.Dataset#convertToUnsignedC(Object, Object)
209     * @see #convertFromUnsignedC(Object data_in)
210     *
211     * @return the converted data buffer.
212     */
213    @Override
214    public Object convertToUnsignedC() {
215        log.trace("convertToUnsignedC(): start");
216        // keep a copy of original buffer and the converted buffer
217        // so that they can be reused later to save memory
218        log.trace("convertToUnsignedC(): unsigned={}", getDatatype().isUnsigned());
219        if ((data != null) && getDatatype().isUnsigned()) {
220            log.trace("convertToUnsignedC(): convert");
221            convertedBuf = data;
222            originalBuf = convertToUnsignedC(convertedBuf, originalBuf);
223            data = originalBuf;
224        }
225
226        log.trace("convertToUnsignedC(): finish");
227        return data;
228    }
229
230    /**
231     * Returns the palette of this scalar dataset or null if palette does not exist.
232     * <p>
233     * A Scalar dataset can be displayed as spreadsheet data or an image. When a scalar dataset is displayed as an
234     * image, the palette or color table may be needed to translate a pixel value to color components (for example, red,
235     * green, and blue). Some scalar datasets have no palette and some datasets have one or more than one palettes. If
236     * an associated palette exists but is not loaded, this interface retrieves the palette from the file and returns the
237     * palette. If the palette is loaded, it returns the palette. It returns null if there is no palette associated with
238     * the dataset.
239     * <p>
240     * Current implementation only supports palette model of indexed RGB with 256 colors. Other models such as
241     * YUV", "CMY", "CMYK", "YCbCr", "HSV will be supported in the future.
242     * <p>
243     * The palette values are stored in a two-dimensional byte array and are arranges by color components of red, green and
244     * blue. palette[][] = byte[3][256], where, palette[0][], palette[1][] and palette[2][] are the red, green and blue
245     * components respectively.
246     * <p>
247     * Sub-classes have to implement this interface. HDF4 and HDF5 images use different libraries to retrieve the
248     * associated palette.
249     *
250     * @return the 2D palette byte array.
251     */
252    public abstract byte[][] getPalette();
253
254    /**
255     * Sets the palette for this dataset.
256     *
257     * @param pal
258     *            the 2D palette byte array.
259     */
260    public final void setPalette(byte[][] pal) {
261        palette = pal;
262    }
263
264    /**
265     * Reads a specific image palette from file.
266     * <p>
267     * A scalar dataset may have multiple palettes attached to it. readPalette(int idx) returns a specific palette
268     * identified by its index.
269     *
270     * @param idx
271     *            the index of the palette to read.
272     *
273     * @return the image palette
274     */
275    public abstract byte[][] readPalette(int idx);
276
277    /**
278     * Get the name of a specific image palette from file.
279     * <p>
280     * A scalar dataset may have multiple palettes attached to it. getPaletteName(int idx) returns the name of a
281     * specific palette identified by its index.
282     *
283     * @param idx
284     *            the index of the palette to retrieve the name.
285     *
286     * @return The name of the palette
287     */
288    public String getPaletteName(int idx) {
289        String paletteName = "Default ";
290        if (idx != 0)
291            paletteName = "Default " + idx;
292        return paletteName;
293    }
294
295    /**
296     * Returns the byte array of palette refs.
297     * <p>
298     * A palette reference is an object reference that points to the palette dataset.
299     * <p>
300     * For example, Dataset "Iceberg" has an attribute of object reference "Palette". The arrtibute "Palette" has value
301     * "2538" that is the object reference of the palette data set "Iceberg Palette".
302     *
303     * @return null if there is no palette attribute attached to this dataset.
304     */
305    public abstract byte[] getPaletteRefs();
306
307    /**
308     * Returns true if this dataset is an image.
309     * <p>
310     * For all Images, they must have an attribute called "CLASS". The value of this attribute is "IMAGE". For more
311     * details, read <a href="https://support.hdfgroup.org/HDF5/doc/ADGuide/ImageSpec.html"> HDF5 Image and Palette Specification</a>
312     *
313     * @return true if the dataset is an image; otherwise, returns false.
314     */
315    public final boolean isImage() {
316        return isImage;
317    }
318
319    /**
320     * Returns true if this dataset is displayed as an image.
321     * <p>
322     * A ScalarDS can be displayed as an image or a spreadsheet in a table.
323     *
324     * @return true if this dataset is displayed as an image; otherwise, returns false.
325     */
326    public final boolean isImageDisplay() {
327
328        return isImageDisplay;
329    }
330
331    /**
332     * Returns true if this dataset is displayed as an image with default image order.
333     * <p>
334     * A ScalarDS can be displayed as an image with different orders of dimensions.
335     *
336     * @return true if this dataset is displayed as an image with default image order; otherwise, returns false.
337     */
338    public final boolean isDefaultImageOrder() {
339        return isDefaultImageOrder;
340    }
341
342    /**
343     * Sets the flag to display the dataset as an image.
344     *
345     * @param b
346     *            if b is true, display the dataset as an image
347     */
348    public final void setIsImageDisplay(boolean b) {
349        isImageDisplay = b;
350    }
351
352    /**
353     * Sets the flag to indicate this dataset is an image.
354     *
355     * @param b
356     *            if b is true, the dataset is an image.
357     */
358    public final void setIsImage(boolean b) {
359        isImage = b;
360    }
361
362    /**
363     * Sets data range for an image.
364     *
365     * @param min
366     *            the data range start.
367     * @param max
368     *            the data range end.
369     */
370    public final void setImageDataRange(double min, double max) {
371        if (max <= min)
372            return;
373
374        if (imageDataRange == null)
375            imageDataRange = new double[2];
376
377        imageDataRange[0] = min;
378        imageDataRange[1] = max;
379    }
380
381    /**
382     * Add a value that will be filtered out in an image.
383     *
384     * @param x
385     *            value to be filtered
386     */
387    public void addFilteredImageValue(Number x) {
388        Iterator<Number> it = filteredImageValues.iterator();
389        while (it.hasNext()) {
390            if (it.next().toString().equals(x.toString()))
391                return;
392        }
393
394        filteredImageValues.add(x);
395    }
396
397    /**
398     * Get a list of values that will be filtered out in an image.
399     *
400     * @return the list of Image values
401     */
402    public List<Number> getFilteredImageValues() {
403        return filteredImageValues;
404    }
405
406    /**
407     * @return true if this dataset is a true color image.
408     *
409     */
410
411    public final boolean isTrueColor() {
412        return isTrueColor;
413    }
414
415    /**
416     * Returns the interlace mode of a true color image (RGB).
417     *
418     * Valid values:
419     *
420     * <pre>
421     *     INTERLACE_PIXEL -- RGB components are contiguous, i.e. rgb, rgb, rgb, ...
422     *     INTERLACE_LINE -- each RGB component is stored as a scan line
423     *     INTERLACE_PLANE -- each RGB component is stored as a plane
424     * </pre>
425     *
426     * @return the interlace mode of a true color image (RGB).
427     */
428    public final int getInterlace() {
429        return interlace;
430    }
431
432    /**
433     * Returns the (min, max) pair of image data range.
434     *
435     * @return the (min, max) pair of image data range.
436     */
437    public double[] getImageDataRange() {
438        return imageDataRange;
439    }
440
441    /**
442     * Returns the fill values for the dataset.
443     *
444     * @return the fill values for the dataset.
445     */
446    @Override
447    public final Object getFillValue() {
448        return fillValue;
449    }
450}