browse_image

function to generate CSLC browse image and image manipulation helper functions

make_browse_image(filename, path_h5, bursts, complex_to_real='amplitude', percent_low=0.0, percent_high=100.0, gamma=1.0, equalize=False)

Make browse image(s) for geocoded CSLC raster(s)

Parameters:

Name	Type	Description	Default
filename		File name of output browse image	required
path_h5		HDF5 file containing geocoded CSLC raster(s)	required
bursts		Burst(s) of geocoded CSLC raster(s)	required
complex_to_real		Method to convert complex float CSLC data to float data. Available methods: amplitude, intensity, logamplitude	'amplitude'
percent_low		Lower percentile of non-NaN pixels to be clipped	0.0
percent_high		Higher percentile of non-NaN pixels to be clipped	100.0
gamma		Exponent value used to gamma correct image	1.0
equalize		Enable/disable histogram equalization	False

Source code in src/compass/utils/browse_image.py

def make_browse_image(filename, path_h5, bursts, complex_to_real='amplitude', percent_low=0.0,
                      percent_high=100.0, gamma=1.0, equalize=False):
    '''
    Make browse image(s) for geocoded CSLC raster(s)

    Parameters
    ----------
    filename: str
        File name of output browse image
    path_h5: str
        HDF5 file containing geocoded CSLC raster(s)
    bursts: list
        Burst(s) of geocoded CSLC raster(s)
    complex_to_real: str
        Method to convert complex float CSLC data to float data. Available
        methods: amplitude, intensity, logamplitude
    percent_low: float
        Lower percentile of non-NaN pixels to be clipped
    percent_high: float
        Higher percentile of non-NaN pixels to be clipped
    gamma: float
        Exponent value used to gamma correct image
    equalize: bool
        Enable/disable histogram equalization
    '''
    # determine how to transform complex imagery in gdal warp
    if complex_to_real not in ['amplitude', 'intensity', 'logamplitude']:
        raise ValueError(f'{complex_to_real} invalid complex to real transform')
    derived_ds_str = f'DERIVED_SUBDATASET:{complex_to_real.upper()}'

    # prepend transform to NETCDF path to grid
    derived_netcdf_to_grid = f'{derived_ds_str}:NETCDF:{path_h5}:/{DATA_PATH}'

    with h5py.File(path_h5, 'r', swmr=True) as h5_obj:
        grid_group = h5_obj[DATA_PATH]

        for b in bursts:
            # get polarization to extract geocoded raster
            pol = b.polarization

            # compute browse shape
            full_shape = grid_group[pol].shape
            browse_h, browse_w = _scale_to_max_pixel_dimension(full_shape)

            # create in memory GDAL raster for GSLC as real value array
            src_raster = f'{derived_netcdf_to_grid}/{pol}'

            min_x, max_x, min_y, max_y = get_georaster_bounds(path_h5, pol)

            # Check if the raster crosses antimeridian
            if max_x - min_x > 180.0:
                gdal.SetConfigOption('CENTER_LONG', '180')
                # Adjust the min / max in the X direction (longitude)
                min_x, max_x = max_x, min_x + 360.0
            else:
                gdal.SetConfigOption('CENTER_LONG', None)

            # gdal warp to right geo extents, image shape and EPSG
            ds_wgs84 = gdal.Warp('', src_raster, format='MEM',
                                 dstSRS='EPSG:4326',
                                 width=browse_w, height=browse_h,
                                 resampleAlg=gdal.GRIORA_Bilinear,
                                 dstNodata=float('nan'),
                                 outputBounds=(min_x, min_y, max_x, max_y)
                                )
            image = ds_wgs84.ReadAsArray()

            # get hi/lo values by percentile
            image, vmin, vmax = _clip_by_percentage(image, percent_low,
                                                    percent_high)

            if equalize:
                image = _image_histogram_equalization(image)

            # scale valid pixels to 1-255
            # set NaNs set to 0 to be transparent
            image = _normalize_apply_gamma(image, vmin, vmax, gamma)

            # save to disk
            _save_to_disk_as_greyscale(image, filename)