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}