Skip to main content

In preparation for the launch of the NASA/Indian Space Research Organization (ISRO) Synthetic Aperture Radar (NISAR) platform, NASA’s Jet Propulsion Laboratory (JPL) has developed some sample NISAR products for users to explore. These sample data give users an idea of what the NISAR data products will look like once the mission is operational. The sample data provide the opportunity to get familiar with formats and develop workflows that will support NISAR datasets.

View the NISAR Sample Data Product Suite for links to all available official sample products.

NASA’s Alaska Satellite Facility Distributed Active Archive Center (ASF DAAC) has developed this document to assist in working with the sample data products using various software suitable for visualizing, analyzing, and transforming geospatial data. Included are sections for working with the data in a GIS environment (ArcGIS Pro and QGIS), exploring the data using Panoply, and transforming the data using GDAL commands.

ArcGIS Visualization/Exploration

This section demonstrates how to use ArcGIS Pro to explore NISAR sample data. Unless otherwise noted, this documentation was generated using ArcGIS Pro version 3.3.0, and assumes that you have ArcGIS Pro open, a new project open based on the Map template, and access to both the Contents and Catalog panes.

You can also work with these products in ArcGIS Pro version 3.2.x, and differences in the illustrations will be largely cosmetic. But ArcGIS Pro 3.1.x and earlier may interact differently with the products than the behavior described in this document.

The filenames for the NISAR products are very long. This can cause problems on Windows machines if they are stored deep in a directory structure or if the directory names are also long. Consider storing these products in a directory close to the root to avoid exceeding the maximum character limit for Windows paths.

Click on a product type to view the steps for Visualization/Exploration using ArcGIS.

There are two sample GCOV products available, one for each of the acquisitions used in other sample products that require imagery pairs:

NISAR_L2_PR_GCOV_001_030_A_019_2000_SHNA_A_20081012T060910_20081012T060926_D00402_N_F_J_001.h5

NISAR_L2_PR_GCOV_002_030_A_019_2000_SHNA_A_20081127T060959_20081127T061015_D00402_N_F_J_001.h5

The illustrations displayed in this document use the acquisition from November 27, 2008.

HDF5 Format

All NISAR products will be in HDF5 format, but they are formatted in such a way that most software applications need to treat them as if they are netCDF files.

First, let’s explore what happens if we try to add the h5 file to the project.

  1. Navigate to the directory with the sample data files in the Catalog pane
    • Note that the .h5 files are listed in the Catalog pane and are available to drag and drop into the project.
    • When you add the HDF5 file to your map, it displays the L-band HH GCOV data in the map, but ArcGIS cannot access the spatial reference information and places the raster off the west coast of Africa. In the illustration below, the raster shows up as a small purple rectangle in the ocean.
Screenshot of ArcGIS

If you add the entire HDF5 file to the project, either by using the drag-and-drop method or by clicking the Add Data button and selecting the HDF5 file, you can access all of the variables in the dataset using the Multidimensional menu. Note that the Multidimensional menu only appears once you add a multidimensional dataset to your project and select it in the Contents pane.

By default, the first variable in the dataset will display in the map, but you can choose to display any of the other variables by selecting it from the drop-down list. The name displayed in the Contents pane will not change, but the map does display the data of the selected variable. You can adjust the symbology as appropriate for the variable you have selected.

Note that only the variables in the grids group will reliably display on the map. Many of the variables in the metadata group are not suitable for visualization.

Screenshot of HDF5 variables in ArcGis

2. To view the raster properties, either right-click the file in the Catalog pane or right-click the layer in the Contents pane and select Properties. It’s easier to see the key properties in a unified view when accessing the properties from the Catalog pane rather than the Contents pane.


 

Screenshot of ArcGIS catalog properties
  • Note that the Spatial Reference is listed as Unknown

There is no metadata formatted in a way that can be accessed using the View Metadata option (right-click the file in Catalog pane), so the only insight into the dataset is what is displayed in the fields included in the dataset properties.

Treat HDF5 as NetCDF

The spatial reference information is encoded in the product using the CF metadata conventions, which were developed for use with NetCDF files. As such, if the GIS software recognizes the file as being a NetCDF, it can parse the spatial reference information and place the raster in the correct location. The current workaround for working with the NISAR HDF5 files in geospatial workflows is to rename the file with a .nc extension in place of the .h5 extension.

Change the File Extension

  1. Browse to the HDF5 file in either a file explorer window or in the Catalog pane of your ArcGIS project.
  2. Edit the filename, changing the .h5 extension to .nc.
    • Note that once the extension has been changed, the file is no longer visible in the Catalog pane in ArcGIS. You can still add the file using the Add Data interface, but there will be no indication in the Catalog pane that this file exists.
    • You can also copy and paste the .h5 file, and rename the copied file with the .nc extension. This can serve as a reminder that the data exists, but it takes up more storage space.
Screenshot of ArcGIS

Add Single Variable from Multidimensional Raster to Project

  1. Click on the bottom half of the Add Data icon in the Map menu ribbon to display the menu, and select Multidimensional Raster Layer from the list of options.
    • Note that if you just use the generic Add Data option, you will be able to navigate to the .nc file, but there will be an error if you try to add it to the map, as it requires the functionality of the Multidimensional Raster Layer option to access the variables within the .nc file.
  2. Click on the folder icon and browse for the NetCDF version of the HDF5 file.
    • Note that HDF5 files are indicated by a blue raster icon, while NetCDF files are indicated by a multilayer grayscale raster icon.
  3. Select the NetCDF file and click OK. The variables in the HDF5 file will be listed.
Screenshot of ArcGIS with multidimensional raster

4. Check the box next to the radar backscatter variable to add it to the project. In this sample product, only one polarization is available.

5. Use the drop-down menu for the Output Configuration parameter to select Multiband Raster.

  • It is critical to select this option; ArcGIS will not render the data if any of the multidimensional options are selected for the Output Configuration.
  • It is possible to select multiple variables to combine into a single multiband raster, if desired. For most geospatial analysis applications, this is probably less convenient than adding the variables separately, but it is a convenient way to add many variables to the map at once for a quick exploration. Refer to the Add Multiple Variables from Multidimensional Raster to Project section for more details.

6. Click OK to load the variable into the map.

Screenshot of ArcGIS select variable feature

Adjust Stretch

As with most SAR backscatter images in power scale, the image appears mostly black when it’s added to the map. You can adjust the stretch settings to view features in the image.

  1. Right-click on the layer in the Contents pane and select Symbology
Screenshot of ArcGIS symbology

2. Adjust the settings to visualize the layer as desired. Common approaches include:

  • Set the Stretch Type to Standard Deviation and adjust the Number of standard deviations value as desired. – For this sample image, 0.5 seems to be a reasonable value. – Changing the Gamma value from 1 to 2 reduces the amount of contrast in the mid-level grayscale values, adding more nuance to the image.
Screenshot of ArcGIS symbology selection
  • Set the Stretch Type to Minimum Maximum and select Custom from the Statistics drop-down menu. This allows you to set a specific range of values to use for the grayscale in the Min and Max fields. Use the tab button after entering each value so that the label field is updated appropriately.
    • Normally, we would expect power values for RTC products to fall mostly between about 0 and 0.03, so we’ll use those for the Minimum and Maximum values.
    • Again, adjusting the Gamma setting changes the character of the visualization.
Screenshot of ArcGIS min/max boundaries

Add Multiple Variables from Multidimensional Raster to Project

This option could be particularly useful when there are multiple polarizations that you want to visualize quickly, especially if you want to use the different polarizations in different channels to display an RGB Decomposition.

  1. Follow the same steps as in Add Single Variable from Multidimensional Raster to Project to select the NetCDF and list the variables.
  2. Check the boxes next to the variables you want to include.
    • Only the variables in the /grids/ group in the HDF5 file are suitable to use when adding multiband rasters with multiple variables.
  3. Select the Multiband Raster from the Output Configuration drop-down menu, and click OK to add the multiband raster to the image.
Screenshot of ArcGIS multiband menu

4. Adjust the symbology to visualize the different bands as desired. By default, if three different variables are included, the image will be visualized as an RGB image with each of the variables assigned to a different band. If fewer than three variables are included, the image will be a grayscale stretch, and you can select which variable to display from the Symbology menu.

  1. It is critical to allow the imagery to render fully each time you change a symbology setting before adjusting another symbology setting.

    For example, if you change to a Standard Deviation stretch, allow the image to render fully before changing the number of standard deviations.

Here are some notes on visualization options:

  • In some cases, it may make sense to keep the RGB visualization. This could be particularly powerful if you’re interested in combining the variables to display particular properties. The best use case is probably for images with multiple polarizations, but because the sample data only includes HH, there are no other polarizations available to be used in combination with HH to generate an RGB decomposition.
    • In this illustration, three variables available in the grid group are assigned to the RGB channels. Because the backscatter values are so small compared to the range of values in the other two variables, there is essentially no red in the image.


 

Screenshot of ArcGIS RGB channels
  • You can adjust the stretch type within the RGB image to highlight particular values/features. However, the variables available for use in this example do not offer a particularly compelling use case for this functionality.
    • In this illustration, changing the stretch type to Standard Deviation allows you to see areas with high backscatter in relation to the other two variables.
    • Setting the number of standard deviations to 0.5 would make the range of backscatter values even more obvious.
Screenshot of ArcGIS standard deviation settings
  • When two variables are added (rather than three), the image displays as grayscale stretch by default, and you have to choose which variable to display. You can, however, change the symbology from Stretch to RGB and assign one of the variables to two of the color bands.
    • This would be particularly useful for dual-pol imagery, where a common approach for is to apply the co-pol (usually HH for NISAR) data to the Red and Blue channels, and the cross-pol (usually HV for NISAR) data to the Green channel.

Note: The illustrations in this section display the previous version of the sample data, and use ArcGIS Pro version 3.2.2 rather than 3.3.0. The workflow is the same with the new products, and there are only minor changes in the ArcGIS interface.

The sample GUNW data file is:

NISAR_L2_PR_GUNW_001_030_A_019_002_2000_SH_20081012T060912_20081012T060924_20081127T061001_20081127T061013_D00402_M_P_J_001.h5

Note that most of the variables in this file have float or integer pixel types, but the wrapped phase variable has a complex pixel type. ArcGIS can display all of the variables, but refer to the Wrapped Phase section for details on how to appropriately visualize complex datasets. This table describes the pixel types for all of the variables included in the grids group of the h5 file:

VariablePixel Type
/science/LSAR/GUNW/grids/frequencyA/pixelOffsets/HH/alongTrackOffset32-bit float
/science/LSAR/GUNW/grids/frequencyA/pixelOffsets/HH/correlationSurfacePeak32-bit float
/science/LSAR/GUNW/grids/frequencyA/pixelOffsets/HH/slantRangeOffset32-bit float
/science/LSAR/GUNW/grids/frequencyA/unwrappedInterferogram/HH/coherenceMagnitude32-bit float
/science/LSAR/GUNW/grids/frequencyA/unwrappedInterferogram/HH/connectedComponents32-bit unsigned integer
/science/LSAR/GUNW/grids/frequencyA/unwrappedInterferogram/HH/ionospherePhaseScreen32-bit float
/science/LSAR/GUNW/grids/frequencyA/unwrappedInterferogram/HH/ionospherePhaseScreenUncertainty32-bit float
/science/LSAR/GUNW/grids/frequencyA/unwrappedInterferogram/HH/unwrappedPhase32-bit float
/science/LSAR/GUNW/grids/frequencyA/unwrappedInterferogram/mask8-bit char
/science/LSAR/GUNW/grids/frequencyA/wrappedInterferogram/HH/coherenceMagnitude32-bit float
/science/LSAR/GUNW/grids/frequencyA/wrappedInterferogram/HH/wrappedInterferogram64-bit complex

Data from this file can be accessed using the same workflow described for the GCOV Product.

  • Change the file extension from .h5 to .nc
  • Use the Multidimensional Raster Layer option in the Add Data menu to browse to the .nc product and select the variables to add to the map.
Screenshot of ArcGIS add GUNW feature

The most common variables to visualize are the wrapped and unwrapped interferograms and the coherence magnitude, but any of the variables in the \grids\ subgroup are rasters that can be displayed in a GIS environment.

Screenshot of ArcGIS GUNW variables

As with the GCOV products, the output configuration selected when adding variables must be Multiband Raster, but you can choose to add individual variables as separate rasters (technically a single-band raster, but still defined as a multiband raster), or select multiple variables to be added to the map together in a single multiband raster (that truly includes multiple bands, each with a different variable).

In general, if you’re interested in optimizing the visualization of a raster, it’s better to add the variable of interest by itself, rather than as a multiband raster that includes other variables. The more you tweak the symbology, the more likely you are to lose the connection to the file, and have to start over. If there’s only one variable included in the multiband raster, it seems to be more robust to symbology adjustments. That said, the connection to the source data can be lost even with a single-variable raster, especially if a symbology adjustment is made that calls for statistics.

When you first add a raster to the map, the variable names usually show up in the list of bands in the Symbology tab. This is the case both for rasters with multiple variables included, and those with just a single variable displayed in the raster, both for greyscale and RGB. This is an easy way to determine which variable you’re exploring.

Screenshot of ArcGIS Unwrapped Interferogram Band

Sometimes the band name gets lost, however, especially after changes are made to the symbology. Instead of the variable name being displayed in the Symbology tab, there is just the generic Band number listed. Because the name of the variable is not displayed in the contents pane by default, it is easy to lose track of which variable the raster represents. You may want to rename the raster layer in the Contents pane, or add an identifier to the end of the existing layer name.

In the illustration below, the wrapped interferogram variable name is no longer displayed in the Band field of the Symbology tab, so we can identify it by right-clicking the layer in the Contents pane, and selecting Properties. In the Source section, the Name field displays both the filename and the variable path.

Screenshot of ArcGIS unwrapped interferogram

Note that there is an option to Set Data Source in the properties. Normally, if you lose a connection to a dataset, you can use that option to select the source file and repair the connection. Unfortunately, because the .nc files are not recognized as ‘files’ by ArcGIS, this is not a viable option to use if you lose the connection to the file while adjusting the symbology. If you try to navigate to the folder with the .nc files, only the .h5 files are listed.

Wrapped Phase

The wrapped phase variable has a complex pixel type, containing both real and imaginary components that can be used to calculate either the amplitude or the phase. When looking at an interferogram to detect and quantify surface deformation, we’re interested in differences in phase rather than in amplitude. By default, however, ArcGIS displays the image in terms of the amplitude values instead of the phase, with pixel values ranging from 2.78641e-12 to 7.37396e-05 for the sample dataset.

Starting with version 3.0, ArcGIS Pro provides a ‘Complex’ raster function, which can be used to display the phase values instead of amplitude values. It is included in the SAR section of the raster functions panel in ArcGIS Pro.

  1. Add the wrapped interferogram variable to the map
    • You may want to rename the layer to ‘wrapped interferogram’ if there are already multiple layers from the NetCDF file, as it will make it easier to select the appropriate layer in the raster function interface
  2. From the Imagery menu, select Raster Functions to open the Raster Functions panel
  3. Type Complex in the search bar at the top of the Raster Functional panel, and click on the Complex raster function
  4. Select the wrapped interferogram layer in both the Raster and the Imaginary Raster fields
  5. Select Phase from the Value Type drop-down menu
  6. Click the Create New Layer button to display a layer showing the Phase values instead of the Amplitude values
Screenshot of ArcGIS Wrapped Interferogram Phase RFT

The values displayed in the image now range from -pi to pi, which is what we would expect for a wrapped interferogram.

Note that the phase layer is a virtual raster that is displayed on-the-fly in your project, but you can export the layer as a stand-alone raster if you would like to save it for future use in other applications.

Coherence

There are two different coherence magnitude variables included: unwrapped coherence magnitude and wrapped coherence magnitude. They have slight differences in their values, but it’s unclear why. There doesn’t appear to be any guidance on which one would be preferable to use for particular applications.

Screenshot of ArcGIS Coherence Differences

Both versions have values ranging from 0 to 1, as expected for coherence values, and are easily displayed in grayscale without having to adjust the scale. In this illustration, both images were set to have a Min-Max stretch from 0 to 1 so that they could be compared visually, but the actual dataset min-max values are also displayed next to the functional scalebar for each image.

Screenshot of ArcGIS Coherence Comparison

Mask

There is a layover-shadow mask included as a variable. It uses various integers to represent certain conditions, but I have not been able to find a reference for what the values represent. It is most useful to display this layer with a Discrete symbology, which applies a different color for each pixel value. In the sample data, there are three different pixel values present: 0, 2 and 127.

0 appears to indicate that there are no quality flags, and 127 indicates the padding pixels around the valid data. The pixels with a value of 2 are generally in the mountains, but it’s unclear if it indicates layover, shadow, foreshortening, or a combination of multiple conditions.

Screenshot of ArcGIS mask

Click on the color patch next to each value in the symbology pane to manually select colors for each individual value. It can be helpful to set the 0 values to be transparent when viewing the mask in relation to an interferogram raster.

The sample GOFF data file is:

NISAR_L2_PR_GOFF_001_030_A_019_002_2000_SH_20081012T060912_20081012T060924_20081127T061001_20081127T061013_D00402_M_P_J_001.h5

There are 21 variables included in the grid group, seven variables for each of three different layers, generated with different window sizes. They are all 32-bit float datasets.

Data from this file can be accessed using the same workflow described for the GCOV Product.

  • Change the file extension from .h5 to .nc
  • Use the Multidimensional Raster Layer option in the Add Data menu to browse to the .nc product and select the variables to add to the map.
Screenshot of ArcGIS

You may find it helpful to apply a color ramp to the products, rather than the default grayscale. In the Symbology settings for the layer, click the Color scheme menu to select a ramp that has two different colors at the extremities with a neutral color in between.
 

Screenshot of ArcGIS GOFF color

The sample SME2 data file is:

NISAR_L3_PR_SME2_001_008_D_070_4000_QPNA_A_20190829T180759_20190829T180809_P01101_M_P_J_001.h5

There are three different variables containing soil moisture data: DSG (Disaggregated), TSR (Time Series Rates), and PMI (Physical Model Inversion).

Data from this file can be accessed using the same workflow described for the GCOV Product.

  • Change the file extension from .h5 to .nc
  • Use the Multidimensional Raster Layer option in the Add Data menu to browse to the .nc product and select the variables to add to the map.

One key difference with this product is that you can add the variables using the Multidimensional Output Configuration. The other types of products require setting this option to Multiband Raster, but the SME2 variables can be added using either of these output configurations.

Screenshot of ArcGIS SME2

Adding a variable as a multidimensional raster allows access to the Multidimensional menu in the ribbon, but only the added variable will be accessible to select when using those tools.

Screenshot of ArcGIS SME2 multidimensional

Even if you select multiple variables and add them using the Multidimensional configuration, they will each be added to the map individually. Again, if you select one of the layers in the Contents pane, you can access the Multidimensional menu, but will only be able to access the variable represented in the layer. The name of the variable is added to the layer name in the Contents pane, which is very helpful.

Screenshot of ArcGIS SME2 Multidimensional Multivariate configuration option

To select multiple variables and add them to the map as a single content item, use the Multidimensional Multivariate configuration option.

Screenshot of ArcGIS multidimensional multivariate configuration option

This adds all the variables you select as a single layer in the Contents pane. When you select the layer, the Multidiminsional menu becomes available, and you can select the variable you want to visualize using the drop-down menu.

Screenshot of ArcGIS with variable selection menu

You can also use the Multiband Raster configuration to generate an RGB image from three variables.

Screenshot of ArcGIS Multiband Raster configuration

In the Symbology tab, use the dropdown menus to select which variable to display for each color band.

Screenshot of ArcGIS  Symbology tab

QGIS Visualization/Exploration

This section demonstrates how to use QGIS to explore NISAR sample data.

Click on a product type to view the steps for Visualization/Exploration using QGIS.

In order to load the images into QGIS, you will have to replace the .h5 file extension with .nc. This is because the NISAR data is actually formatted like a NetCDF file, rather than HDF5. If you try to use the regular .h5 files, QGIS will likely crash (with no error or warning) when you choose a layer (refer to the QGIS Crashes section for more information). If you load the .h5 file, QGIS may continue to crash even after renaming to .nc. This may be fixed by deleting the .aux.xml file that QGIS creates in the same directory as the dataset.

Once you have the file named, you can simply drag and drop it into the QGIS window. This should bring up a prompt to select the desired layers. In our case, we want the layer that ends with HHHH.

Screenshot of QGIS loading the layer that ends with HHHH

You should now have something that looks like this:

Screenshot of QGIS visualization without symbology

By default, QGIS scales the color map based off of the min and max. This leads to a dark image. We can fix this by changing the way that QGIS scales the color map. We can do this by right-clicking the layer and selecting Properties. We can then go to Symbology -> Min / Max Value Settings and select Cumulative Cut Count.

Screenshot of QGIS cumulative cut count screen

Now, things should look much better.

Screenshot of QGIS cumulative cut count visualization

If you would like color, rather than a black-and-white image, you can click on the Render Type drop-down box in the Symbology page and select singleband psuedocolor. For this, you will also want to use Cumulative Cut Count.

Screenshot of QGIS visualization in color

Selecting the Desired Groups/Layers/Sub-Datasets

Just like the GCOV products, we will first need to replace the .h5 extension with .nc, otherwise the projection information will be incorrect. Once the extension is replaced, we can drag the file into QGIS as normal and then select the desired layers. For this demonstration we will select the unwrappedInterferogram/HH/coherenceMagnitude and unwrappedInterferogram/HH/unwrappedPhase layers.

Screenshot of QGIS selection menu

Unwrapped Phase

Now that the layers are added, we can right-click and zoom to the unwrapped phase layer. You should have something that looks like this:

Screenshot of QGIS with layers added

While this image is relatively clear and interpretable, we can modify the symbology to bring out some more detail. We can do this by right-clicking the layer and selecting Properties. We can then go to Symbology -> Min / Max Value Settings and select Cumulative Cut Count or Mean +/- standard deviation.

Screenshot of QGIS, select cumulative cut count

When color is desired, you can also switch the Render Type to singleband psuedocolor in the same menu.

Screenshot of QGIS GUNW visualization with color

Coherence Magnitude

The coherence magnitude image should look good by default, but the same process that we applied to the unwrapped image can be applied if desired.

QGIS screenshot of the coherence magnitude image

Wrapped Phase

Unlike the unwrapped phase and coherence magnitude, the wrapped phase data uses a complex data type. Unfortunately QGIS won’t natively handle complex data, so we will have to extract the phase component using this GDAL command:

gdal_translate -of GTiff DERIVED_SUBDATASET:PHASE:path/to/nisar.nc:/science/LSAR/GUNW/grids/frequencyA/wrappedInterferogram/HH/wrappedInterferogram phase.tif

We can then load the GeoTIFF image into QGIS as normal. It should look good by default, but you can modify the Symbology in the same manner as the unwrapped phase, if desired.

Screenshot of QGIS image with symbology modified

After changing the extension from .h5 to .nc, we can drag the file into QGIS and select the desired layers. Here, we will visualize the alongTrackOffset layer.

Screenshot of the GOFF product in QGIS with layer selection

You can visualize the data without changing the symbology, but you can try varying the Min/Max Value Settings in the Symbology section of the layer properties if desired.

Screenshot of the GOFF visualization in QGIS

After changing the extension from .h5 to .nc, we can drag the file into QGIS and select the desired layers. Here, we will visualize the Soil_moisture layer.

Screenshot of QGIS layer selection

The image should be easy to visually interpret by default.

Screenshot of QGIS SME visualization without color

If desired, we can also add colored symbology and modify the Min/Max Value Settings. This will add more contrast, and can make things easier to interpret.

Screenshot of QGIS color selection menu

Once that is done, the image should look this:

Screenshot of QGIS SME visualization with color

QGIS does not have a way of natively viewing complex valued data, but we can use GDAL to extract the amplitude and phase components into separate real-valued images. Since the amplitude component contains the visual information, we will extract that using the following GDAL command:

gdal_translate -of GTiff DERIVED_SUBDATASET:AMPLITUDE:NETCDF:/path/to/nisar.nc:/science/LSAR/GSLC/grids/frequencyA/HH amplitude.tif

Note that we can also extract the phase component by replacing :AMPLITUDE: with :PHASE: if needed.

We can now load the image into QGIS.

Screenshot of QGIS GSLC visualization with no adjustment

Without adjustments, the image will usually appear black. This is because QGIS defines the color range based on the maximum and minimum values, but SAR tends to have a small number of bright pixels that expand the dynamic range far beyond the majority of the pixel values. In order to visualize surface features, we can set the Min/Max Value Settings to Mean +/- standard deviation x in the Symbology section of the layer’s properties. This prevents the small number of very bright pixels from disproportionately affecting the grayscale range.

Screenshot of QGIS symbology selection

The image should then look like this:

Screenshot of QGIS GSLC visualization once adjusted

Panoply Exploration

This section demonstrates how to use NASA's Panoply software to explore NISAR sample data.

This documentation assumes you have installed Panoply, and downloaded the NISAR sample data to a directory named nisar_sample_data on your local machine. The sample data package includes one Level-0 data file (L0B), four Level-1 data files (RSLC, RIFG, RUNW, ROFF), four Level-2 data files (GSLC, GUNW, GOFF, GCOV), and one Level-3 data file (SME2). We are going to explore and/or visualize each product.

Level-0 and Level-1 data

Level-0 (L0b) and Level-1 (RSLC, RIFG, RUNW, and ROFF) can be loaded in Panoply correctly. Users can explore the data structure of these products. Since they are not projected into map space, we do not visualize them.

Click on a product type to view the steps for Exploration of the sample data using Panoply.

The GUNW data file is

NISAR_L2_PR_GUNW_001_030_A_019_002_2000_SH_20081012T060912_20081012T060924_20081127T061001_20081127T061013_D00402_M_P_J_001.h5

1). Open the File

cd ${path_to_panoply}
./panoply.sh

The Panoply user interface opens as shown below.

Screenshot of the Panoply user interface
  • Navigate to the directory with the file in the Open window
  • Click on the NISAR_L2_PR_GUNW_001_030_A_019_002_2000_SH_20081012T060912_20081012T060924_20081127T061001_20081127T061013_D00402_M_P_J_001.h5 file
  • Click the Open button to load the file into Panoply, as shown below
Screenshot of Panoply directory with the file in the Open window

The right panel shows the structure of the file as well as the metadata. You can use this interface to inspect file information. The left panel provides users the option to select the dataset they want to use.

Expand the drop-down menu to find the “unwrappedPhase” dataset, which we will visualize in the following steps.

Screenshot on Panoply, where the right panel shows the structure of the file as well as the metadata, and the left panel provides users the option to select the dataset they want to use.

2) Create Plot

Once you select the dataset to use (in this case, unwrappedPhase), click the Create Plot button right below the main menu. A dialogue window opens with options for the type of plot to create.

Screenshot of Panoply Create Plot dialogue window open with options for the type of plot to create.

Select Color contour plot, then click the create button in the dialogue window to display the plot window.

Screenshot of Panoply displaying the plot window

3) Customize the Plot

Users can control the plot properties by clicking window in the pull-down menu of the plot window.

As an example, to change the scale to show off the variation of unwrappedPhase:

  • Select Plot Controls to open the Plot Controls window
  • Select scale
  • Change the min value to -8.426141, and keep the max 8.426141 unchanged

The new plot displays the variation clearly.

Screenshot of Panoply showing the variation of unwrappedPhase

4) Save the Plot

When you are satisfied with the plot, you can save the results.

  • Select File in the main menu of plot window
  • Select Save Image to open the Save As… window
  • Select the directory, and either accept the default filename or input the filename of your choice
  • Click the save button to save the plot
Screenshot of Panoply visualization of GUNW data

The example GOFF product is:

NISAR_L2_PR_GOFF_001_030_A_019_002_2000_SH_20081012T060912_20081012T060924_20081127T061001_20081127T061013_D00402_M_P_J_001.h5

Use the same process detailed in the GUNW Product section to visualize the GOFF product.

Screenshot of Panoply visualization of the NISAR GOFF product

The sample data package includes two GCOV products:

NISAR_L2_PR_GCOV_001_030_A_019_2000_SHNA_A_20081012T060910_20081012T060926_D00402_N_F_J_001.h5

NISAR_L2_PR_GCOV_002_030_A_019_2000_SHNA_A_20081127T060959_20081127T061015_D00402_N_F_J_001.h5

They can be loaded directly in Panoply. Users can explore the data structure of the products and can visualize the 2D variables in the products. We will use the acquisition from 12-Oct-2008 in the illustrations.

For example, we visualize two variables here.

radar_backscatter_gamma0

Screenshot of steps to visualize the two variables.

rtcGammaToSigmaFactor

Screenshot of steps to change variables.

You may need to open the Plot Control window and adjust the grid, scale, and map projection to get a suitable visualization.

If you choose to create a Georeferenced longitude-latitude color contour plot for a 2D variable, you may need to extract the variable and save it into a NetCDF file, then visualize the NetCDF file. For example, if we want to visualize the rtcGammaToSigmaFactor 2D variable in the file:

gdal_translate -of NetCDF NETCDF:"NISAR_L2_PR_GCOV_001_030_A_019_2000_SHNA_A_20081012T060910_20081012T060926_D00402_N_F_J_001.h5"://science/LSAR/GCOV/grids/frequencyA/rtcGammaToSigmaFactor rtcAreaNormalizationFactorGamma0ToSigma0.nc

Load the NetCDF file into Panoply and plot the variable by choosing the Georeferenced plot type. You may need to open the Plot Control window and adjust the grid, scale, and map projection to get a suitable visualization.

This is the original display of rtcAreaNormalizationFactorGamma0ToSigma0.nc file in Panoply:

Screenshot of the RTC Area Normalization

The map projection, scale, and grid adjustments are made in the Plot Control window to visualize the rtcAreaNormalizationFactorGamma0ToSigma0.nc file appropriately:

See this video for a demonstration.

After applying the adjustments, the rtcAreaNormalizationFactorGamma0ToSigma0.nc file is displayed as illustrated below.

Screenshot of result after applying corrections

There are two GSLC products included in the sample data:

NISAR_L2_PR_GSLC_001_030_A_019_2000_SHNA_A_20081012T060910_20081012T060926_D00402_N_F_J_001.h5

NISAR_L2_PR_GSLC_002_030_A_019_2000_SHNA_A_20081127T060959_20081127T061015_D00402_F_N_J_001.h5

These files can be loaded into Panoply. We will use the acquisition from 12-Oct-2008 in the illustrations.

Screenshot of the loaded files in Panoply

We can explore the datasets in the product. Since the variable HH is complex data, it can not be visualized directly. We can extract the sub-datasets in the h5 file using GDAL, and then visualize these sub-datasets in Panoply.

The subdataset is a complex datatype, so we cannot use the gdal_translate command to convert a complex dataset directly into a NetCDF file. Instead, we use the following logic to generate a file that can be used to visualize the subdataset:

1) Convert the subdataset into a geotiff file

gdal_translate -of GTiff NETCDF:"NISAR_L2_PR_GSLC_001_005_A_219_2005_DHDH_A_20081127T060959_20081127T061015_P01101_N_F_J_001.h5"://science/LSAR/GSLC/grids/frequencyA/HH hh.tif

2) Convert the single-band Complex32 dataset into a two-band Float32 GeoTIFF file

from osgeo import gdal
import numpy as np
gdal.UseExceptions()
file="hh.tif"
outfile = "hh_polar.tif"
ds = gdal.Open(file)
band = ds.GetRasterBand(1)
data = band.ReadAsArray()
amp = abs(data)
phase = np.angle(data)
# create output raster file
driver = gdal.GetDriverByName("GTiff")
outdata = driver.Create(outfile, ds.RasterXSize, ds.RasterYSize, 2, gdal.GDT_Float64)
outdata.SetGeoTransform(ds.GetGeoTransform())
outdata.SetProjection(ds.GetProjection())
outdata.SetMetadata(ds.GetMetadata())
outdata.GetRasterBand(1).WriteArray(amp)
outdata.GetRasterBand(1).SetMetadata({"bandname": "modulus"})
outdata.GetRasterBand(2).WriteArray(phase)
outdata.GetRasterBand(2).SetMetadata({"bandname": "argument"})
outdata = None

3) Convert the GeoTIFF file to a NetCDF file

gdal_translate -of NetCDF hh_polar.tif hh_polar.nc

4) Use Panoply to visualize the amplitude and phase data in the NetCDF file

Amplitude data

Screenshot of amplitude data

Phase data 

Screenshot of phase data result

The sample SME2 data is:

NISAR_L3_PR_SME2_001_008_D_070_4000_QPNA_A_20190829T180759_20190829T180809_P01101_M_P_J_001.h5

The SME2 product sub-datasets can be displayed using the same process we used for the GUNW product.

For example, the water body fraction sub-dataset is displayed here:

Screenshot of the water body fraction sub-dataset

and the landcover sub-dataset is displayed here:

Screenshot of the landcover sub-dataset is displayed

GDAL Data Access/Transformation

This section guides accessing and transforming NISAR HDF5-formatted data with GDAL, using the GCOV sample dataset as the primary test case.

One important thing to remember is that the NISAR HDF5 products are actually more similar to NetCDFs. Notably, the spatial reference data is encoded using NetCDF Climate and Forecast (CF) Metadata Conventions. This means you need to specify an output format for some commands, otherwise GDAL will throw an error like ERROR 1: Cannot guess driver for output.h5. It also means that you should prepend the NISAR files with NETCDF:. This approach is demonstrated throughout the examples in this section. Note that while the formats are slightly different, you can still access the sub-datasets or groups the same way you would with an HDF5 file.

Access detailed info on what each of the products contain and sample data.

Run this command to get a list of the sub-datasets and the paths that you need to use with your commands:

gdalinfo path/to/NISAR.h5 | grep "SUBDATASET_\d*_DESC"

Converting the NISAR data will require you to specify a sub-dataset (also known as a group). Failure to supply one will result in an error like Input file contains subdatasets. Please, select one of them for reading.

The examples below choose to convert only the HH to HH covariance portion of GCOV product. This data is most similar to our current co-polarizated RTC products.

Using the Command Line

gdal_tranlsate -of GTiff NETCDF:"path/to/input.h5":/science/LSAR/GCOV/grids/frequencyA/HHHH path/to/output.tif

Using Python

h5_file = 'NETCDF:"path/to/input.h5":/science/LSAR/GCOV/grids/frequencyA/HHHH'
out_file = 'path/to/output.tif'
gdal.Translate(out_file, h5_file, format='GTiff')

Reprojecting the NISAR data will require you to specify which sub-dataset you would like to reproject. Failure to specify the sub-dataset will result in an error like ERROR 1: Input file NETCDF:NISAR_L2_PR_GCOV_001_005_A_219_4020_SHNA_A_20081012T060910_20081012T060926_P01101_F_N_J_001.h5 has no raster bands.

Using the Command Line

gdalwarp -of GTiff -t_srs EPSG:XXXX NETCDF:"path/to/input.h5":/science/LSAR/GCOV/grids/frequencyA/HHHH path/to/output.tif

Using Python

h5_file = 'NETCDF:"path/to/input.h5":/science/LSAR/GCOV/grids/frequencyA/HHHH'
out_file = 'path/to/output.tif'
gdal.Warp(tif_file, h5_file, format='GTiff', dstSRS='EPSG:XXXX')

At this time, we do not know of a simple way of reprojecting an entire dataset. You will need to individually reproject each subdataset that you are interested in.

A sub-dataset can be clipped to a geographic extent using gdalwarp. The existing extent of the sub-dataset can be found by calling gdalinfo on it. Note that you won’t find the extent by calling gdalinfo on the entire dataset.

Using the Command Line

gdalwarp -of GTiff -te xmin ymin xmax ymax NETCDF:"path/to/input.h5":/science/LSAR/GCOV/grids/frequencyA/HHHH path/to/output.tif

Using Python

h5_file = 'NETCDF:"path/to/input.h5":/science/LSAR/GCOV/grids/frequencyA/HHHH'
out_file = 'path/to/output.tif'
gdal.Warp(out_file, h5_file, format='GTiff', outputBounds=[xmin, ymin, xmax, ymax])

Note that the Command Line method only adds the main images to the multiband GTiff without the H5s additional metadata. The Python method is more complicated, but it will place all subdatasets into the GTiff, as well as the additional related metadata.

Using the Command Line

file="path/to/input.h5"
subdataset1="${file}://science/LSAR/GCOV/grids/frequencyA/HHHH"
subdataset2="${file}://science/LSAR/GCOV/grids/frequencyA/numberOfLooks"
subdataset3="${file}://science/LSAR/GCOV/grids/frequencyA/rtcAreaNormalizationFactorGamma0ToSigma0"
dimensions_args="-ul_lr upper_left_corner_x upper_left_corner_y lower_right_corner_x lower_right_corner_y -ps pixel_size_x pixel_size_y"
gdal_merge.py $dimensions_args -seperate -of GTiff -o $(echo $file | sed 's/\.h5/\_multiband.tif/g')

Using Python

Here is the code to extract raster subsets in h5 and convert them into geotiff files.

import json
import subprocess
import re
from osgeo import gdal

file="NISAR_L2_PR_GCOV_001_005_A_219_4020_SHNA_A_20081012T060910_20081012T060926_P01101_F_N_J_001.h5"
actual_json = json.loads(subprocess.check_output(f"gdalinfo -json {file}", shell=True))
datasets = actual_json['metadata']['SUBDATASETS']
names = [key for key in datasets.keys() if re.match('SUBDATASET_[0-9]*_NAME', key)]
for name in names:
    subdata = f"{datasets[name].replace('HDF5','NETCDF')}"
    if gdal.Open(subdata).GetProjectionRef() != '':
        outfile =f"{subdata.replace('/','_')}.tif"
        subprocess.run(f'gdal_translate -of GTiff {subdata} {outfile}', shell=True)

We also provide the code to combine all raster subdatasets with the same datatype, extent, size, and projection in the h5 into multiple-band geotiff files. We notice that the combined multiple band geotiff files do not include the metadata for each band in the geotiff files.

import json
import subprocess
import re
import numpy as np
from osgeo import gdal

def combine_geotiff(filelist, outfile):
    '''
    Merge the geotiff files with the same data type, extent, and projection into a multiple band geotif file
    :param filelist: list of geotiff files
    :param outfile: filename of the output file
    :return: None
    '''
    bandmetalist = [gdal.Info(file, format='json')['bands'] for file in filelist]
    bandnumlist = [len(item) for item in bandmetalist]
    bandnum = int(np.array(bandnumlist).sum())
    filenum = len(filelist)
    for i in range(filenum):
        ds = gdal.Open(filelist[i])
        if i == 0:
            # create output raster file
            driver = gdal.GetDriverByName("GTiff")
            outdata = driver.Create(outfile, ds.RasterXSize, ds.RasterYSize, bandnum, ds.GetRasterBand(1).DataType )
            outdata.SetGeoTransform(ds.GetGeoTransform())  ##sets same geotransform as input
            outdata.SetProjection(ds.GetProjection())  ##sets same projection as input
        bandnum_of_file = ds.RasterCount
        fmeta = ds.GetMetadata()
        for j in range(1, bandnum_of_file + 1):
            band = ds.GetRasterBand(j)
            outdata.GetRasterBand(i*bandnum_of_file + j).WriteArray(band.ReadAsArray())
            fmeta.update(band.GetMetadata())
            outdata.GetRasterBand(i*bandnum_of_file + j).SetMetadata(fmeta)
        ds = None
    outdata = None
file="NISAR_L2_PR_GCOV_001_005_A_219_4020_SHNA_A_20081012T060910_20081012T060926_P01101_F_N_J_001.h5"
actual_json = json.loads(subprocess.check_output(f"gdalinfo -json {file}", shell=True))
datasets = actual_json['metadata']['SUBDATASETS']
names = [key for key in datasets.keys() if re.match('SUBDATASET_[0-9]*_NAME', key)]
datalist=[]
for name in names:
    subdata = f"{datasets[name].replace('HDF5','NETCDF')}"
    ds = gdal.Open(subdata)
    if ds.GetProjectionRef() != '':
        size = f'{ds.RasterXSize}x{ds.RasterYSize}'
        outfile = f"{subdata.replace('/','_')}.tif"
        outfile = outfile.split(":")[2].replace('__','')
        mo=outfile.replace(".tif","")
        subprocess.run(f"gdal_translate -of GTiff -ot Float32 -mo Band={mo} {subdata} {outfile}", shell=True)
        datalist.append({"filename":outfile, "size":size})     
sizelist = [item['size'] for item in datalist]
uniqvals= np.unique(sizelist)
for item in uniqvals: 
    itemlist = [ dataitem['filename'] for dataitem in datalist if dataitem['size'] == item ]
    mb_outfile = subdata.split(":")[1].replace('.h5',f'_{item}.tif')
    mb_outfile = mb_outfile.replace('"','')
    combine_geotiff(itemlist, mb_outfile)

Details

Last Updated

Published

Data Archive

Alaska Satellite Facility DAAC (ASF DAAC)