1.. _raster.hdf4: 2 3================================================================================ 4HDF4 -- Hierarchical Data Format Release 4 (HDF4) 5================================================================================ 6 7.. shortname:: HDF4 8 9.. shortname:: HDF4Image 10 11.. build_dependencies:: libdf 12 13There are two HDF formats, HDF4 (4.x and previous releases) and HDF5. 14These formats are completely different and NOT compatible. This driver 15intended for HDF4 file formats importing. NASA's Earth Observing System 16(EOS) maintains its own HDF modification called HDF-EOS. This 17modification is suited for use with remote sensing data and fully 18compatible with underlying HDF. This driver can import HDF4-EOS files. 19Currently EOS use HDF4-EOS for data storing (telemetry form \`Terra' and 20\`Aqua' satellites). In the future they will switch to HDF5-EOS format, 21which will be used for telemetry from \`Aura' satellite. 22 23Driver capabilities 24------------------- 25 26.. supports_createcopy:: 27 28.. supports_create:: 29 30.. supports_georeferencing:: 31 32Multiple Image Handling (Subdatasets) 33------------------------------------- 34 35Hierarchical Data Format is a container for several different datasets. 36For data storing Scientific Datasets (SDS) used most often. SDS is a 37multidimensional array filled by data. One HDF file may contain several 38different SDS arrays. They may differ in size, number of dimensions and 39may represent data for different regions. 40 41If the file contains only one SDS that appears to be an image, it may be 42accessed normally, but if it contains multiple images it may be 43necessary to import the file via a two step process. The first step is 44to get a report of the components images (SDS arrays) in the file using 45**gdalinfo**, and then to import the desired images using 46gdal_translate. The **gdalinfo** utility lists all multidimensional 47subdatasets from the input HDF file. The name of individual images 48(subdatasets) are assigned to the **SUBDATASET_n_NAME** metadata item. 49The description for each image is found in the **SUBDATASET_n_DESC** 50metadata item. For HDF4 images the subdataset names will be formatted 51like this: 52 53*HDF4_SDS:subdataset_type:file_name:subdataset_index* 54 55where *subdataset_type* shows predefined names for some of the well 56known HDF datasets, *file_name* is the name of the input file, and 57*subdataset_index* is the index of the image to use (for internal use in 58GDAL). 59 60On the second step you should provide this name for **gdalinfo** or 61**gdal_translate** for actual reading of the data. 62 63For example, we want to read data from the MODIS Level 1B dataset: 64 65:: 66 67 $ gdalinfo GSUB1.A2001124.0855.003.200219309451.hdf 68 Driver: HDF4/Hierarchical Data Format Release 4 69 Size is 512, 512 70 Coordinate System is `' 71 Metadata: 72 HDFEOSVersion=HDFEOS_V2.7 73 Number of Scans=204 74 Number of Day mode scans=204 75 Number of Night mode scans=0 76 Incomplete Scans=0 77 78...a lot of metadata output skipped... 79 80:: 81 82 Subdatasets: 83 SUBDATASET_1_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:0 84 SUBDATASET_1_DESC=[408x271] Latitude (32-bit floating-point) 85 SUBDATASET_2_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:1 86 SUBDATASET_2_DESC=[408x271] Longitude (32-bit floating-point) 87 SUBDATASET_3_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:2 88 SUBDATASET_3_DESC=[12x2040x1354] EV_1KM_RefSB (16-bit unsigned integer) 89 SUBDATASET_4_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:3 90 SUBDATASET_4_DESC=[12x2040x1354] EV_1KM_RefSB_Uncert_Indexes (8-bit unsigned integer) 91 SUBDATASET_5_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:4 92 SUBDATASET_5_DESC=[408x271] Height (16-bit integer) 93 SUBDATASET_6_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:5 94 SUBDATASET_6_DESC=[408x271] SensorZenith (16-bit integer) 95 SUBDATASET_7_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:6 96 SUBDATASET_7_DESC=[408x271] SensorAzimuth (16-bit integer) 97 SUBDATASET_8_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:7 98 SUBDATASET_8_DESC=[408x271] Range (16-bit unsigned integer) 99 SUBDATASET_9_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:8 100 SUBDATASET_9_DESC=[408x271] SolarZenith (16-bit integer) 101 SUBDATASET_10_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:9 102 SUBDATASET_10_DESC=[408x271] SolarAzimuth (16-bit integer) 103 SUBDATASET_11_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:10 104 SUBDATASET_11_DESC=[408x271] gflags (8-bit unsigned integer) 105 SUBDATASET_12_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:12 106 SUBDATASET_12_DESC=[16x10] Noise in Thermal Detectors (8-bit unsigned integer) 107 SUBDATASET_13_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:13 108 SUBDATASET_13_DESC=[16x10] Change in relative responses of thermal detectors (8-bit unsigned integer) 109 SUBDATASET_14_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:14 110 SUBDATASET_14_DESC=[204x16x10] DC Restore Change for Thermal Bands (8-bit integer) 111 SUBDATASET_15_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:15 112 SUBDATASET_15_DESC=[204x2x40] DC Restore Change for Reflective 250m Bands (8-bit integer) 113 SUBDATASET_16_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:16 114 SUBDATASET_16_DESC=[204x5x20] DC Restore Change for Reflective 500m Bands (8-bit integer) 115 SUBDATASET_17_NAME=HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:17 116 SUBDATASET_17_DESC=[204x15x10] DC Restore Change for Reflective 1km Bands (8-bit integer) 117 Corner Coordinates: 118 Upper Left ( 0.0, 0.0) 119 Lower Left ( 0.0, 512.0) 120 Upper Right ( 512.0, 0.0) 121 Lower Right ( 512.0, 512.0) 122 Center ( 256.0, 256.0) 123 124Now select one of the subdatasets, described as 125``[12x2040x1354] EV_1KM_RefSB (16-bit unsigned integer)``: 126 127:: 128 129 $ gdalinfo HDF4_SDS:MODIS_L1B:GSUB1.A2001124.0855.003.200219309451.hdf:2 130 Driver: HDF4Image/HDF4 Internal Dataset 131 Size is 1354, 2040 132 Coordinate System is `' 133 Metadata: 134 long_name=Earth View 1KM Reflective Solar Bands Scaled Integers 135 136...metadata skipped... 137 138:: 139 140 Corner Coordinates: 141 Upper Left ( 0.0, 0.0) 142 Lower Left ( 0.0, 2040.0) 143 Upper Right ( 1354.0, 0.0) 144 Lower Right ( 1354.0, 2040.0) 145 Center ( 677.0, 1020.0) 146 Band 1 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 147 Band 2 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 148 Band 3 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 149 Band 4 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 150 Band 5 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 151 Band 6 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 152 Band 7 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 153 Band 8 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 154 Band 9 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 155 Band 10 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 156 Band 11 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 157 Band 12 Block=1354x2040 Type=UInt16, ColorInterp=Undefined 158 159Or you may use **gdal_translate** for reading image bands from this 160dataset. 161 162Note that you should provide exactly the contents of the line marked 163**SUBDATASET_n_NAME** to GDAL, including the **HDF4_SDS:** prefix. 164 165This driver is intended only for importing remote sensing and geospatial 166datasets in form of raster images. If you want explore all data 167contained in HDF file you should use another tools (you can find 168information about different HDF tools using links at end of this page). 169 170Georeference 171------------ 172 173There is no universal way of storing georeferencing in HDF files. 174However, some product types have mechanisms for saving georeferencing, 175and some of these are supported by GDAL. Currently supported are 176(*subdataset_type* shown in parenthesis): 177 178- HDF4 files created by GDAL (**GDAL_HDF4**) 179- ASTER Level 1A (**ASTER_L1A**) 180- ASTER Level 1B (**ASTER_L1B**) 181- ASTER Level 2 (**ASTER_L2**) 182- ASTER DEM (**AST14DEM**) 183- MODIS Level 1B Earth View products (**MODIS_L1B**) 184- MODIS Level 3 products (**MODIS_L3**) 185- SeaWiFS Level 3 Standard Mapped Image Products (**SEAWIFS_L3**) 186 187By default the hdf4 driver only reads the gcps from every 10th row and 188column from EOS_SWATH datasets. You can change this behavior by setting 189the GEOL_AS_GCPS environment variable to PARTIAL (default), NONE, or 190FULL. 191 192Creation Issues 193--------------- 194 195This driver supports creation of the HDF4 Scientific Datasets. You may 196create set of 2D datasets (one per each input band) or single 3D dataset 197where the third dimension represents band numbers. All metadata and band 198descriptions from the input dataset are stored as HDF4 attributes. 199Projection information (if it exists) and affine transformation 200coefficients also stored in form of attributes. Files, created by GDAL 201have the special attribute: 202 203"Signature=Created with GDAL (http://www.remotesensing.org/gdal/)" 204 205and are automatically recognised when read, so the projection info and 206transformation matrix restored back. 207 208Creation Options: 209 210- **RANK=n**: Create **n**-dimensional SDS. Currently only 2D and 3D 211 datasets supported. By default a 3-dimensional dataset will be 212 created. 213 214Metadata 215-------- 216 217All HDF4 attributes are transparently translated as GDAL metadata. In 218the HDF file attributes may be assigned assigned to the whole file as 219well as to particular subdatasets. 220 221Open options 222------------ 223 224The following open option is supported: 225 226- **LIST_SDS=AUTO/YES/NO**: (GDAL >= 3.2) Whether to report Scientific Data Sets (SDS). 227 By default, when a HDF file contains EOS_SWATH or EOS_GRID, SDS will not be 228 listed as GDAL subdatasets (as this would cause them to be reported twice). 229 Listing them can be forced by setting LIST_SDS to YES. 230 231 232Multidimensional API support 233---------------------------- 234 235.. versionadded:: 3.1 236 237The HDF4 driver supports the :ref:`multidim_raster_data_model` for reading 238operations. 239 240Driver building 241--------------- 242 243This driver built on top of NCSA HDF library, so you need one to compile 244GDAL with HDF4 support. You may search your operating system 245distribution for the precompiled binaries or download source code or 246binaries from the NCSA HDF Home Page (see links below). 247 248Please note, that NCSA HDF library compiled with several defaults which 249is defined in *hlimits.h* file. For example, *hlimits.h* defines the 250maximum number of opened files: 251 252:: 253 254 # define MAX_FILE 32 255 256If you need open more HDF4 files simultaneously you should change this 257value and rebuild HDF4 library (and relink GDAL if using static HDF 258libraries). 259 260See Also 261-------- 262 263- Implemented as ``gdal/frmts/hdf4/hdf4dataset.cpp`` and 264 ``gdal/frmts/hdf4/hdf4imagedataset.cpp``. 265- `The HDF Group <http://www.hdfgroup.org/>`__ 266- Sources of the data in HDF4 and HDF4-EOS formats: 267 268 `Earth Observing System Data 269 Gateway <http://edcimswww.cr.usgs.gov/pub/imswelcome/>`__ 270 271Documentation to individual products, supported by this driver: 272 273- `Geo-Referencing ASTER L1B 274 Data <http://edcdaac.usgs.gov/aster/ASTER_GeoRef_FINAL.pdf>`__ 275- `ASTER Standard Data Product Specifications 276 Document <http://asterweb.jpl.nasa.gov/documents/ASTERHigherLevelUserGuideVer2May01.pdf>`__ 277- `MODIS Level 1B Product Information and 278 Status <http://www.mcst.ssai.biz/mcstweb/L1B/product.html>`__ 279- `MODIS Ocean User's 280 Guide <http://modis-ocean.gsfc.nasa.gov/userguide.html>`__ 281