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
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
|
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.72 [en] (WinNT; U) [Netscape]">
<title>Image Specification</title>
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B" alink="#FF0000">
<hr>
<center><table BORDER=0 WIDTH="98%" >
<tr>
<td ALIGN=LEFT VALIGN=TOP><a href="../index.html">HDF5 documents and links</a>
<br><a href="../H5.intro.html">Introduction to HDF5</a>
<br><a href="../RM_H5Front.html">HDF5 Reference Manual</a>
<br><!--
<a href="../Glossary.html">Glossary</a><br>
--></td>
<td ALIGN=RIGHT VALIGN=TOP>
<br><a href="../H5.user.html">HDF5 User's Guide</a>
<br><a href="../ADGuide.html">HDF5 Application Developer's Guide</a></td>
</tr>
</table></center>
<hr>
<center>
<h1>
HDF5 Image and Palette Specification</h1></center>
<center>
<h3>
<i>Version 1.2</i></h3></center>
The HDF5 specification defines the standard objects and storage for the
standard HDF5 objects. (For information about the HDF5 library, model and
specification, see the HDF documentation.) This document is an additional
specification do define a standard profile for how to store image data
in HDF5. Image data in HDF5 is stored as HDF5 datasets with standard attributes
to define the properties of the image.
<p>This specification is primarily concerned with two dimensional raster
data similar to HDF4 Raster Images. Specifications for storing other
types of imagery will be covered in other documents.
<p>This specification defines:
<ul>
<li>
Standard storage and attributes for an Image dataset (<a href="#Sect1">Section
1</a>)</li>
<li>
Standard storage and attributes for Palettes (<a href="#sect2">Section
2</a>)</li>
<li>
Standard for associating Palettes with Images. (<a href="#Sect3">Section
3</a>)</li>
</ul>
<h2>
<a NAME="Sect1"></a>1. HDF5 Image Specification</h2>
<h3>
1.1 Overview</h3>
Image data is stored as an HDF5 dataset with values of HDF5 class Integer
or Float. A common example would be a two dimensional dataset, with
elements of class Integer, e.g., a two dimensional array of unsigned 8
bit integers. However, this specification does not limit the dimensions
or number type that may be used for an Image.
<p>The dataset for an image is distinguished from other datasets by giving
it an attribute "CLASS=IMAGE". In addition, the Image dataset may
have an optional attribute "PALETTE" that is an array of object references
for zero or more palettes. The Image dataset may have additional attributes
to describe the image data, as defined in <a href="#Sect1.2">Section 1.2</a>.
<p>A Palette is an HDF5 dataset which contains color map information.
A Pallet dataset has an attribute "CLASS=PALETTE" and other attributes
indicating the type and size of the palette, as defined in <a href="#sect2">Section
2.1</a>. A Palette is an independent object, which can be shared
among several Image datasets.
<h3>
<a NAME="Sect1.2"></a>1.2 Image Attributes</h3>
The attributes for the Image are scalars unless otherwise noted.
The length of String valued attributes should be at least the number of
characters. Optionally, String valued attributes may be stored in a String
longer than the minimum, in which case it must be zero terminated or null
padded. "Required" attributes must always be used. "Optional" attributes
must be used when required.
<br>
<h4>
Attributes</h4>
<dl>
<dt>
Attribute name="<b>CLASS</b>" (Required)</dt>
<dd>
This attribute is type H5T_C_S1, with size 5.</dd>
<dd>
For all Images, the value of this attribute is "IMAGE".</dd>
<dd>
</dd>
<dd>
This attribute identifies this data set as intended to be interpreted as
an image that conforms to the specifications on this page.</dd>
</dl>
<dt>
Attribute name="<b>PALETTE</b>"</dt>
<dl>
<dd>
A Image dataset within an HDF5 file may optionally specify an array of
palettes to be viewed with. The dataset will have an attribute field called
"<b>PALETTE</b>" which contains a one-dimensional array of object reference
pointers (HDF5 datatype H5T_STD_REF_OBJ) which refer to palettes in the
file. The palette datasets must conform to the Palette specification in
<a href="#sect2">section
2 below</a>. The first palette in this array will be the default palette
that the data may be viewed with.</dd>
</dl>
<dl>
<dt>
</dt>
<dt>
Attribute name="<b>IMAGE_SUBCLASS</b>"</dt>
<dd>
If present, the value of this attribute indicates the type of Palette that
should be used with the Image. This attribute is a scalar of type
H5T_C_S1, with size according to the string plus one. The values
are:</dd>
<dl>
<dt>
"IMAGE_GRAYSCALE" (length 15)</dt>
<dd>
A grayscale image, values 0-255 indicating brightness.</dd>
<dt>
"IMAGE_BITMAP" (length 12)</dt>
<dd>
A bit map image</dd>
<dt>
"IMAGE_TRUECOLOR" (length 15)</dt>
<dd>
A truecolor image</dd>
<dt>
"IMAGE_INDEXED" (length 13)</dt>
<dd>
An indexed image</dd>
<dd>
</dd>
</dl>
<dt>
Attribute name="<b>INTERLACE_MODE</b>"</dt>
<dd>
For images with more than one component for each pixel, this optional attribute
specifies the layout of the data. The values are type H5T_C_S1 of length
15. See <a href="#Section1.3">section 1.3</a> for information about the
storage layout for data.</dd>
<dd>
"INTERLACE_PIXEL" (default): the component value for a pixel are contiguous.</dd>
<dd>
"INTERLACE_PLANE": each component is stored as a plane.</dd>
<dt>
</dt>
<dt>
Attribute name="<b>DISPLAY_ORIGIN</b>"</dt>
<dd>
This optional attribute indicates the intended orientation of the data
on a two-dimensional raster display. The value indicates which corner
the pixel at (0, 0) should be viewed. The values are type H5T_C_S1
of length 2. If DISPLAY_ORIGIN is not set, the orientation is undefined.</dd>
<dd>
"UL": (0,0) is at the upper left.</dd>
<dd>
"LL": (0,0) is at the lower left.</dd>
<dd>
"UR": (0,0) is at the upper right.</dd>
<dd>
"LR": (0,0) is at the lower right.</dd>
</dl>
<dt>
Attribute name="<b>IMAGE_WHITE_IS_ZERO</b>"</dt>
<dl>
<dd>
This attribute is of type H5T_NATIVE_UCHAR. 0 = false, 1 = true .
This is used for images with IMAGE_SUBCLASS="IMAGE_GRAYSCALE" or "IMAGE_BITMAP".</dd>
</dl>
<dl>
<dt>
Attribute name="<b>IMAGE_MINMAXRANGE</b>"</dt>
<dd>
If present, this attribute is an array of two numbers, of the same HDF5
datatype as the data. The first element is the minimum value of the
data, and the second is the maximum. This is used for images with
IMAGE_SUBCLASS="IMAGE_GRAYSCALE", "IMAGE_BITMAP" or "IMAGE_INDEXED".</dd>
</dl>
<dt>
Attribute name="<b>IMAGE_BACKGROUNDINDEX</b>"</dt>
<dl>
<dd>
If set, this attribute indicates the index value that should be interpreted
as the "background color". This attribute is HDF5 type H5T_NATIVE_UINT.</dd>
</dl>
<dt>
Attribute name="<b>IMAGE_TRANSPARENCY</b>"</dt>
<dl>
<dd>
If set, this attribute indicates the index value that should be interpreted
as the "transparent color". This attribute is HDF5 type H5T_NATIVE_UINT.
This attribute may not be used for IMAGE_SUBCLASS="IMAGE_TRUE_COLOR".</dd>
</dl>
<dt>
Attribute name="<b>IMAGE_ASPECTRATIO</b>"</dt>
<dl>
<dd>
If set, this attribute indicates the aspect ratio. This attribute
is HDF5 type H5T_NATIVE_UINT.</dd>
</dl>
<dt>
Attribute name="<b>IMAGE_COLORMODEL</b>"</dt>
<dl>
<dd>
If set, this attribute indicates the color model of Palette that should
be used with the Image. This attribute is of type H5T_C_S1, with
size 3, 4, or 5. The value is one of the color models described in
the Palette specification in <a href="#sect2.2">section 2.2 below</a>.
This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR" or
"IMAGE_INDEXED".</dd>
</dl>
<dt>
Attribute name="<b>IMAGE_GAMMACORRECTION</b>"</dt>
<dl>
<dd>
If set, this attribute gives the Gamma correction. The attribute
is type H5T_NATIVE_FLOAT. This attribute may be used only for IMAGE_SUBCLASS="IMAGE_TRUECOLOR"
or "IMAGE_INDEXED".</dd>
</dl>
Attribute name="<b>IMAGE_VERSION</b>" (Required)
<dl>
<dd>
This attribute is of type H5T_C_S1, with size corresponding to the length
of the version string. This attribute identifies the version number
of this specification to which it conforms. The current version number
is "1.2".</dd>
<br>
<p>
<br>
<br>
<center><table BORDER=2 BGCOLOR="#FFFFFF" >
<caption><b>Table 1. Attributes of an Image Dataset</b></caption>
<tr>
<td><b>Attribute Name</b></td>
<td><b>(R = Required</b>
<br><b>O= Optional)</b></td>
<td><b>Type</b></td>
<td><b>String Size</b></td>
<td><b>Value</b></td>
</tr>
<tr>
<td>CLASS</td>
<td>R</td>
<td>String</td>
<td>5</td>
<td>"IMAGE"</td>
</tr>
<tr>
<td>PALETTE</td>
<td>O</td>
<td>Array Object References</td>
<td></td>
<td><references to Palette datasets><sup>1</sup></td>
</tr>
<tr>
<td>IMAGE_SUBCLASS</td>
<td>O<sup>2</sup></td>
<td>String</td>
<td>15,
<br>12,
<br>15,
<br>13</td>
<td>
<dt>
"IMAGE_GRAYSCALE",</dt>
<dt>
"IMAGE_BITMAP",</dt>
<dt>
"IMAGE_TRUECOLOR",</dt>
<dt>
"IMAGE_INDEXED"</dt>
</td>
</tr>
<tr>
<td>INTERLACE_MODE</td>
<td>O<sup>3,6</sup></td>
<td>String</td>
<td>15</td>
<td>The layout of components if more than one component per pixel.</td>
</tr>
<tr>
<td>DISPLAY_ORIGIN</td>
<td>O</td>
<td>String</td>
<td>2</td>
<td>If set, indicates the intended location of the pixel (0,0).</td>
</tr>
<tr>
<td>IMAGE_WHITE_IS_ZERO</td>
<td>O<sup>3,4</sup></td>
<td>Unsigned Integer</td>
<td></td>
<td>0 = false, 1 = true</td>
</tr>
<tr>
<td>IMAGE_MINMAXRANGE</td>
<td>O<sup>3,5</sup></td>
<td>Array [2] <same datatype as data values></td>
<td></td>
<td>The (<minimum>, <maximum>) value of the data.</td>
</tr>
<tr>
<td>IMAGE_BACKGROUNDINDEX</td>
<td>O<sup>3</sup></td>
<td>Unsigned Integer</td>
<td></td>
<td>The index of the background color.</td>
</tr>
<tr>
<td>IMAGE_TRANSPARENCY</td>
<td>O<sup>3,5</sup></td>
<td>Unsigned Integer</td>
<td></td>
<td>The index of the transparent color.</td>
</tr>
<tr>
<td>IMAGE_ASPECTRATIO</td>
<td>O<sup>3,4</sup></td>
<td>Unsigned Integer</td>
<td></td>
<td>The aspect ratio.</td>
</tr>
<tr>
<td>IMAGE_COLORMODEL</td>
<td>O<sup>3,6</sup></td>
<td>String</td>
<td>3, 4, or 5</td>
<td>The color model, as defined below in the Palette specification for
attribute <b>PAL_COLORMODEL</b>.</td>
</tr>
<tr>
<td>IMAGE_GAMMACORRECTION</td>
<td>O<sup>3,6</sup></td>
<td>Float</td>
<td></td>
<td>The gamma correction.</td>
</tr>
<tr>
<td>IMAGE_VERSION</td>
<td>R</td>
<td>String</td>
<td>3</td>
<td>"1.2"</td>
</tr>
</table></center>
<dl><font size=-1>1. The first element of the array is the default
Palette.</font>
<br><font size=-1>2. This attribute is <b>required</b> for images
that use one of the standard color map types listed.</font>
<br><font size=-1>3. This attribute is <b>required</b> if set for the source
image, in the case that the image is translated from another file into
HDF5.</font>
<br><font size=-1>4. This applies to: IMAGE_SUBCLASS="IMAGE_GRAYSCALE"
or "IMAGE_BITMAP".</font>
<br><font size=-1>5. This applies to: IMAGE_SUBCLASS="IMAGE_GRAYSCALE",
"IMAGE_BITMAP", or "IMAGE_INDEXED".</font>
<br><font size=-1>6. This applies to: IMAGE_SUBCLASS="IMAGE_TRUECOLOR",
or "IMAGE_INDEXED".</font></dl>
</dl>
Table 2 summarizes the standard attributes for an Image datasets using
the common sub-classes. R means that the attribute listed on the leftmost
column is Required for the image subclass on the first row, O means that
the attribute is Optional for that subclass and N that the attribute cannot
be applied to that subclass. The two first rows show the only required
attributes
for all subclasses.
<br>
<table BORDER WIDTH="100%" >
<caption><b>Table 2a. Applicability of Attributes to IMAGE sub-classes</b></caption>
<tr>
<td WIDTH="20%"><b>IMAGE_SUBCLASS</b><sup>1</sup></td>
<td WIDTH="20%"><b>IMAGE_GRAYSCALE</b></td>
<td WIDTH="20%"><b>IMAGE_BITMAP</b></td>
</tr>
<tr>
<td WIDTH="20%">CLASS</td>
<td WIDTH="20%">R</td>
<td WIDTH="20%">R</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_VERSION</td>
<td WIDTH="20%">R</td>
<td WIDTH="20%">R</td>
</tr>
<tr>
<td>INTERLACE_MODE</td>
<td>N</td>
<td>N</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_WHITE_IS_ZERO</td>
<td WIDTH="20%">R</td>
<td WIDTH="20%">R</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_MINMAXRANGE</td>
<td WIDTH="20%">O</td>
<td WIDTH="20%">O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_BACKGROUNDINDEX</td>
<td WIDTH="20%">O</td>
<td WIDTH="20%">O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_TRANSPARENCY</td>
<td WIDTH="20%">O</td>
<td WIDTH="20%">O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_ASPECTRATIO</td>
<td WIDTH="20%">O</td>
<td WIDTH="20%">O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_COLORMODEL</td>
<td WIDTH="20%">N</td>
<td WIDTH="20%">N</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_GAMMACORRECTION</td>
<td WIDTH="20%">N</td>
<td WIDTH="20%">N</td>
</tr>
<tr>
<td WIDTH="20%">PALETTE</td>
<td WIDTH="20%">O</td>
<td WIDTH="20%">O</td>
</tr>
<tr>
<td>DISPLAY_ORIGIN</td>
<td>O</td>
<td>O</td>
</tr>
</table>
<blockquote> </blockquote>
<table BORDER WIDTH="100%" >
<caption><b>Table 2b. Applicability of Attributes to IMAGE sub-classes</b></caption>
<tr>
<td WIDTH="20%"><b>IMAGE_SUBCLASS</b></td>
<td WIDTH="20%"><b>IMAGE_TRUECOLOR</b></td>
<td><b>IMAGE_INDEXED</b></td>
</tr>
<tr>
<td WIDTH="20%">CLASS</td>
<td WIDTH="20%">R</td>
<td>R</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_VERSION</td>
<td WIDTH="20%">R</td>
<td>R</td>
</tr>
<tr>
<td>INTERLACE_MODE</td>
<td>R</td>
<td>N</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_WHITE_IS_ZERO</td>
<td WIDTH="20%">N</td>
<td>N</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_MINMAXRANGE</td>
<td WIDTH="20%">N</td>
<td>O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_BACKGROUNDINDEX</td>
<td WIDTH="20%">N</td>
<td>O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_TRANSPARENCY</td>
<td WIDTH="20%">N</td>
<td>O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_ASPECTRATIO</td>
<td WIDTH="20%">O</td>
<td>O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_COLORMODEL</td>
<td WIDTH="20%">O</td>
<td>O</td>
</tr>
<tr>
<td WIDTH="20%">IMAGE_GAMMACORRECTION</td>
<td WIDTH="20%">O</td>
<td>O</td>
</tr>
<tr>
<td WIDTH="20%">PALETTE</td>
<td WIDTH="20%">O</td>
<td>O</td>
</tr>
<tr>
<td>DISPLAY_ORIGIN</td>
<td>O</td>
<td>O</td>
</tr>
</table>
<h3>
<a NAME="Section1.3"></a>1.3 Storage Layout and Properties for Images</h3>
In the case of an image with more than one component per pixel (e.g., Red,
Green, and Blue), the data may be arranged in one of two ways. Following
HDF4 terminology, the data may be interlaced by pixel or by plane, which
should be indicated by the INTERLACE_MODE attribute. In both
cases, the dataset will have a dataspace with three dimensions, height,
width, and components. The interlace modes specify different orders
for the dimensions.
<br>
<table BORDER COLS=2 WIDTH="100%" >
<caption><b>Table 3. Storage of multiple component image data.</b></caption>
<tr>
<td><b>Interlace Mode</b></td>
<td><b>Dimensions in the Dataspace</b></td>
</tr>
<tr>
<td>INTERLACE_PIXEL</td>
<td>[height][width][pixel components]</td>
</tr>
<tr>
<td>INTERLACE_PLANE</td>
<td>[pixel components][height][width]</td>
</tr>
</table>
<p>For example, consider a 5 (rows) by 10 (column) image, with Red, Green,
and Blue components. Each component is an unsigned byte. In HDF5,
the datatype would be declared as an unsigned 8 bit integer. For
pixel interlace, the dataspace would be a three dimensional array, with
dimensions: [10][5][3]. For plane interleave, the dataspace would
be three dimensions: [3][10][5].
<p>In the case of images with only one component, the dataspace may be
either a two dimensional array, or a three dimensional array with the third
dimension of size 1. For example, a 5 by 10 image with 8 bit color
indexes would be an HDF5 dataset with type unsigned 8 bit integer.
The dataspace could be either a two dimensional array, with dimensions
[10][5], or three dimensions, with dimensions either [10][5][1] or [1][10][5].
<p>Image datasets may be stored with any chunking or compression properties
supported by HDF5.
<p><b>A note concerning compatibility with HDF5 GR interface: </b>An Image
dataset is stored as an HDF5 dataset. It is important to note that
the order of the dimensions is the same as for any other HDF5 dataset.
For a two dimensional image that is to be stored as a series of horizontal
scan lines, with the scan lines contiguous (i.e., the fastest changing
dimension is 'width'), the image will have a dataspace with <i>dim[0] =
height</i> and <i>dim[1]</i> = <i>width</i>. This is completely consistent
with all other HDF5 datasets.
<p>Users familiar with HDF4 should be cautioned that <i>this is not the
same as HDF4</i>, and specifically is not consistent with what the HDF4
GR interface does.
<br>
<h2>
<a NAME="sect2"></a>2. HDF5 Palette Specification</h2>
<h3>
2.1 Overview</h3>
A palette is the means by which color is applied to an image and is also
referred to as a color lookup table. It is a table in which every row contains
the numerical representation of a particular color. In the example of an
8 bit standard RGB color model palette, this numerical representation of
a color is presented as a triplet specifying the intensity of red, green,
and blue components that make up each color.
<center>
<p><img SRC="Palettes.fm.anc.gif" ></center>
<p>In this example, the color component numeric type is an 8 bit unsigned
integer. While this is most common and recommended for general use, other
component color numeric datatypes, such as a 16 bit unsigned integer ,
may be used. This type is specified as the type attribute of the palette
dataset. (see H5Tget_type(), H5Tset_type())
<p>The minimum and maximum values of the component color numeric are specified
as attribute of the palette dataset. See below (attribute PAL_MINMAXNUMERIC).
If these attributes do not exist, it is assumed that the range of values
will fill the space of the color numeric type. i.e. with an 8 bit unsigned
integer, the valid range would be 0 to 255 for each color component.
<p>The HDF5 palette specification additionally allows for color models
beyond RGB. YUV, HSV, CMY, CMYK, YCbCr color models are supported, and
may be specified as a color model attribute of the palette dataset. <i>(see
"Palette Attributes" for details)</i>.
<p>In HDF 4 and earlier, palettes were limited to 256 colors. The HDF5
palette specification allows for palettes of varying length. The length
is specified as the number of rows of the palette dataset.
<br>
<br>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#666666" >
<tr>
<td><font color="#FFFFFF">Important Note: The specification of the Indexed
Palette will change substantially in the next version. The Palette
described here is <i>denigrated</i> and is not supported.</font></td>
</tr>
</table>
<br>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td><i>Denigrated</i>
<p>In a standard palette, the color entries are indexed directly. HDF5
supports the notion of a range index table. Such a table defines an ascending
ordered list of ranges that map dataset values to the palette. If a range
index table exists for the palette, the PAL_TYPE attribute will be set
to "RANGEINDEX", and the PAL_RANGEINDEX attribute will contain an object
reference to a range index table array. If not, the PAL_TYPE attribute
either does not exist, or will be set to "STANDARD".
<p>The range index table array consists of a one dimensional array with
the same length as the palette dataset - 1. Ideally, the range index would
be of the same type as the dataset it refers to, however this is not a
requirement.
<p><b>Example 2: A range index array of type floating point</b>
<center>
<p><img SRC="PaletteExample1.gif" ></center>
<p>The range index array attribute defines the "<i>to</i>" of the range.
Notice that the range index array attribute is one less entry in size than
the palette. The first entry of 0.1259, specifies that all values below
and up to 0.1259 inclusive, will map to the first palette entry. The second
entry signifies that all values greater than 0.1259 up to 0.3278 inclusive,
will map to the second palette entry, etc. All value greater than the last
range index array attribute (100000) map to the last entry in the palette.</td>
</tr>
</table>
<h3>
<a NAME="sect2.2"></a>2.2. Palette Attributes</h3>
A palette exists in an HDF file as an independent data set with accompanying
attributes. The Palette attributes are scalars except where noted
otherwise. String values should have size the length of the string
value plus one. "Required" attributes must be used. "Optional"
attributes must be used when required.
<p>These attributes are defined as follows:
<dl>
<dt>
Attribute name="<b>CLASS</b>" (Required)</dt>
<dd>
This attribute is of type H5T_C_S1, with size 7.</dd>
<dd>
For all palettes, the value of this attribute is "PALETTE". This attribute
identifies this palette data set as a palette that conforms to the specifications
on this page.</dd>
<dt>
Attribute name="<b>PAL_COLORMODEL</b>" (Required)</dt>
<dd>
This attribute is of type H5T_C_S1, with size 3, 4, or 5.</dd>
<dd>
Possible values for this are "RGB", "YUV", "CMY", "CMYK", "YCbCr", "HSV".</dd>
<dd>
This defines the color model that the entries in the palette data set represent.</dd>
<dl>
<dt>
"RGB"</dt>
<dd>
Each color index contains a triplet where the the first value defines the
red component, second defines the green component, and the third the blue
component.</dd>
<dt>
"CMY"</dt>
<dd>
Each color index contains a triplet where the the first value defines the
cyan component, second defines the magenta component, and the third the
yellow component.</dd>
<dt>
"CMYK"</dt>
<dd>
Each color index contains a quadruplet where the the first value defines
the cyan component, second defines the magenta component, the third the
yellow component, and the forth the black component.</dd>
<dt>
"YCbCr"</dt>
<dd>
Class Y encoding model. Each color index contains a triplet where the the
first value defines the luminance, second defines the Cb Chromonance, and
the third the Cr Chromonance.</dd>
<dt>
"YUV"</dt>
<dd>
Composite encoding color model. Each color index contains a triplet where
the the first value defines the luminance component, second defines the
chromonance component, and the third the value component.</dd>
<dt>
"HSV"</dt>
<dd>
Each color index contains a triplet where the the first value defines the
hue component, second defines the saturation component, and the third the
value component. The hue component defines the hue spectrum with a low
value representing magenta/red progressing to a high value which would
represent blue/magenta, passing through yellow, green, cyan. A low value
for the saturation component means less color saturation than a high value.
A low value for <i>value</i> will be darker than a high value.</dd>
<dd>
</dd>
</dl>
<dt>
Attribute name="<b>PAL_TYPE</b>" (Required)</dt>
<dd>
This attribute is of type H5T_C_S1, with size 9 or 10.</dd>
<dd>
The current supported values for this attribute are : "STANDARD8" or "RANGEINDEX"</dd>
<dd>
A PAL_TYPE of "STANDARD8" defines a palette dataset such that the first
entry defines index 0, the second entry defines index 1, etc. up until
the length of the palette - 1. This assumes an image dataset with direct
indexes into the palette.</dd>
</dl>
<dl>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td><i>Denigrated</i>
<p>If the PAL_TYPE is set to "RANGEINDEX", there will be an additional
attribute with a name of "<b>PAL_RANGEINDEX</b>", (See example 2
for more details)</td>
</tr>
</table>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td>
<dt>
Attribute name="<b>PAL_RANGEINDEX</b>" <i>(Denigrated)</i></dt>
<dl>
<dd>
The <b>PAL_RANGEINDEX</b> attribute contains an HDF object reference (HDF5
datatype H5T_STD_REF_OBJ) pointer which specifies a range index array in
the file to be used for color lookups for the palette. (Only for
PAL_TYPE="RANGEINDEX")</dd>
</dl>
</td>
</tr>
</table>
<dt>
Attribute name="<b>PAL_MINMAXNUMERIC</b>"</dt>
<dl>
<dt>
If present, this attribute is an array of two numbers, of the same HDF5
datatype as the palette elements or color numerics.</dt>
<br>They specify the minimum and maximum values of the color numeric components.
For example, if the palette was an RGB of type Float, the color numeric
range for Red, Green, and Blue could be set to be between 0.0 and 1.0.
The intensity of the color guns would then be scaled accordingly to be
between this minimum and maximum attribute.</dl>
Attribute name="<b>PAL_VERSION</b>" (Required)
<dl>This attribute is of type H5T_C_S1, with size corresponding to the
length of the version string. This attribute identifies the version
number of this specification to which it conforms. The current version
is "1.2".</dl>
<center><table BORDER=2 BGCOLOR="#FFFFFF" >
<caption><b>Table 4. Attributes of a Palette Dataset</b></caption>
<tr>
<td><b>Attribute Name</b></td>
<td><b>(R = Required,</b>
<br><b>O = Optional)</b></td>
<td><b>Type</b></td>
<td><b>String Size</b></td>
<td><b>Value</b></td>
</tr>
<tr>
<td>CLASS</td>
<td>R</td>
<td>String</td>
<td>
<center>7</center>
</td>
<td>"PALETTE"</td>
</tr>
<tr>
<td>PAL_COLORMODEL</td>
<td>R</td>
<td>String</td>
<td>
<center>3, 4, or 5</center>
</td>
<td>Color Model: "RGB", YUV", "CMY", "CMYK", "YCbCr", or "HSV"</td>
</tr>
<tr>
<td>PAL_TYPE</td>
<td>R</td>
<td>String</td>
<td>
<center>9</center>
<p><br>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td>or 10</td>
</tr>
</table>
</td>
<td>"STANDARD8"
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td>or "RANGEINDEX" <i>(Denigrated)</i></td>
</tr>
</table>
</td>
</tr>
<tr>
<td>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td><i>Denigrated</i>
<br>RANGE_INDEX</td>
</tr>
</table>
</td>
<td></td>
<td>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td>Object Reference </td>
</tr>
</table>
</td>
<td></td>
<td>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td><Object Reference to Dataset of range index values></td>
</tr>
</table>
</td>
</tr>
<tr>
<td>PAL_MINMAXNUMERIC</td>
<td>O</td>
<td>Array[2] of <same datatype as palette></td>
<td></td>
<td>The first value is the <Minimum value for color values>, the second
value is <Maximum value for color values><sup>2</sup></td>
</tr>
<tr>
<td>PAL_VERSION</td>
<td>R</td>
<td>String</td>
<td>4</td>
<td>"1.2"</td>
</tr>
</table></center>
<dl>
<table BORDER COLS=1 WIDTH="100%" BGCOLOR="#CCCCCC" >
<tr>
<td><font size=-1>1. The RANGE_INDEX attribute is required if the
PAL_TYPE is "RANGEINDEX". Otherwise, the RANGE_INDEX attribute should
be omitted. (Range index is denigrated.)</font></td>
</tr>
</table>
<font size=-1>2. The minimum and maximum are optional. If not
set, the range is assumed to the maximum range of the number type.
If one of these attributes is set, then both should be set. The value
of the minimum must be less than or equal to the value of the maximum.</font></dl>
</dl>
Table 5 summarized the uses of the standard attributes for a palette dataset.
R means that the attribute listed on the leftmost column is Required for
the palette type on the first row, O means that the attribute is Optional
for that type and N that the attribute cannot be applied to that type.
The four first rows show the attributes that are always required
for the two palette types.
<br>
<br>
<table BORDER WIDTH="100%" >
<caption><b>Table 5. Applicability of Attributes</b></caption>
<tr>
<td WIDTH="33%"><b>PAL_TYPE</b></td>
<td WIDTH="33%"><b>STANDARD8</b></td>
<td WIDTH="34%"><b>RANGEINDEX</b></td>
</tr>
<tr>
<td WIDTH="33%">CLASS</td>
<td WIDTH="33%">R</td>
<td WIDTH="34%">R</td>
</tr>
<tr>
<td WIDTH="33%">PAL_VERSION</td>
<td WIDTH="33%">R</td>
<td WIDTH="34%">R</td>
</tr>
<tr>
<td WIDTH="33%">PAL_COLORMODEL</td>
<td WIDTH="33%">R</td>
<td WIDTH="34%">R</td>
</tr>
<tr>
<td WIDTH="33%">RANGE_INDEX</td>
<td WIDTH="33%">N</td>
<td WIDTH="34%">R</td>
</tr>
<tr>
<td WIDTH="33%">PAL_MINMAXNUMERIC</td>
<td WIDTH="33%">O</td>
<td WIDTH="34%">O</td>
</tr>
</table>
<h3>
2.3. Storage Layout for Palettes</h3>
The values of the Palette are stored as a dataset. The datatype can
be any HDF 5 atomic numeric type. The dataset will have dimensions
(<tt>nentries</tt> by <tt>ncomponents</tt>), where '<tt>nentries</tt>'
is the number of colors (usually 256) and '<tt>ncomponents'</tt> is the
number of values per color (3 for <b>RGB</b>, 4 for <b>CMYK</b>, etc.)
<br>
<h2>
<a NAME="Sect3"></a>3. Consistency and Correlation of Image and Palette
Attributes</h2>
The objects in this specification are an extension to the base HDF5 specification
and library. They are accessible with the standard HDF5 library,
but the semantics of the objects are not enforced by the base library.
For example, it is perfectly possible to add an attribute called <b>IMAGE</b>
to <i>any</i> dataset, or to include an object reference to <i>any</i>
HDF5 dataset in a <b>PALETTE</b> attribute. This would be a valid
HDF5 file, but not conformant to this specification. The rules defined
in this specification must be implemented with appropriate software, and
applications must use conforming software to assure correctness.
<p>The Image and Palette specifications include several redundant standard
attributes, such as the <b>IMAGE_COLORMODEL</b> and the <b>PAL_COLORMODEL</b>.
These attributes are informative not normative, in that it is acceptable
to attach a Palette to an Image dataset even if their attributes do not
match. Software is not required to enforce consistency, and files
may contain mismatched associations of Images and Palettes. In all
cases, it is up to applications to determine what kinds of images and color
models can be supported.
<p>For example, an Image that was created from a file with an "RGB" may
have a "YUV" Palette in its <b>PALETTE</b> attribute array. This
would be a legal HDF5 file and also conforms to this specification, although
it may or may not be correct for a given application.
<p>
<hr>
<center><table BORDER=0 WIDTH="98%" >
<tr>
<td ALIGN=LEFT VALIGN=TOP><a href="../index.html">HDF5 documents and links</a>
<br><a href="../H5.intro.html">Introduction to HDF5</a>
<br><a href="../RM_H5Front.html">HDF5 Reference Manual</a>
<br><!--
<a href="../Glossary.html">Glossary</a><br>
--></td>
<td ALIGN=RIGHT VALIGN=TOP>
<br><a href="../H5.user.html">HDF5 User's Guide</a>
<br><a href="../ADGuide.html">HDF5 Application Developer's Guide</a></td>
</tr>
</table></center>
<hr>
<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a></address>
<br>
<!-- Created: Spring 1999 -->
<!-- hhmts start -->
Last modified: 3 July 2001
<!-- hhmts end -->
<br>
Describes HDF5 Release 1.5, Unreleased Development Branch
</body>
</html>
|
