Exporting bitmasks — PyEPR 0.8.1 documentation

### Navigation

- index
- next |
- previous |
- PyEPR 0.8.1 documentation »
- Tutorials »

# Exporting bitmasks

This tutorial shows how to generate bit masks from ENVISAT flags information as “raw” image using PyEPR.

The example code (`examples/write_bitmask.py`) is a direct translation of the C sample program write_bitmask.c bundled with the EPR API distribution.

The program is invoked as follows:

    $ python write_bitmask.py <envisat-product> <bitmask-expression> \
    <output-file>

The `examples/write_bitmask.py` code consists in a single function that also includes command line arguments handling:

     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
    #!/usr/bin/env python

    # This program is a direct translation of the sample program
    # "write_bitmask.c" bundled with the EPR-API distribution.
    #
    # Source code of the C program is available at:
    # https://github.com/bcdev/epr-api/blob/master/src/examples/write_bitmask.c

    '''Generates bit mask from ENVISAT flags information as "raw" image
    for (e.g.) Photoshop

    Call::

        $ python write_bitmask.py <envisat-product> <bitmask-expression>
        <output-file>

    Example to call the main function::

        $ python write_bitmask.py MER_RR__2P_TEST.N1 \
        'l2_flags.LAND and !l2_flags.BRIGHT' my_flags.raw

    '''

    from __future__ import print_function

    import sys
    import epr

    def main(*argv):
        if not argv:
            argv = sys.argv

        if len(argv) != 4:
            print('Usage: write_bitmask <envisat-product> <bitmask-expression> '
                  '<output-file>')
            print('  where envisat-product is the input filename')
            print('  and bitmask-expression is a string containing the bitmask '
                  'logic')
            print('  and output-file is the output filename.')
            print('Example:')
            print("  MER_RR__2P_TEST.N1 'l2_flags.LAND and not l2_flags.BRIGHT' "
                  "my_flags.raw")
            print
            sys.exit(1)

        product_file_path = argv[1]
        bm_expr = argv[2]
        image_file_path = argv[3]

        # Open the product; an argument is a path to product data file
        with epr.open(product_file_path) as product:
            offset_x = 0
            offset_y = 0
            source_width = product.get_scene_width()
            source_height = product.get_scene_height()
            source_step_x = 1
            source_step_y = 1

            bm_raster = epr.create_bitmask_raster(source_width, source_height,
                                                  source_step_x, source_step_y)

            product.read_bitmask_raster(bm_expr, offset_x, offset_y, bm_raster)

            with open(image_file_path, 'wb') as out_stream:
                bm_raster.data.tofile(out_stream)

        print('Raw image data successfully written to "%s".' % image_file_path)
        print('Data type is "byte", size is %d x %d pixels.' % (source_width,
                                                                source_height))

    if __name__ == '__main__':
        main()

In order to use the Python EPR API the `epr` module is imported:

    import epr

As usual the ENVISAT product is opened using the `epr.open()` function that returns an `epr.Product` instance. In this case the `epr.open()` is used together with a `with` statement so that the `epr.Product` instance is closed automatically when the program exits the `with` block.

        # Open the product; an argument is a path to product data file
        with epr.open(product_file_path) as product:

Scene size parameters are retrieved form the `epr.Product` object using the `epr.Product.get_scene_width()` and `epr.Product.get_scene_height()` methods:

            source_width = product.get_scene_width()
            source_height = product.get_scene_height()

The EPR API allows to manage data by means of `epr.Raster` objects, so the function `epr.create_bitmask_raster()`, specific for bitmasks, is used to create a `epr.Raster` instance.

See also

`epr.create_raster()`

Data are actually read using the `epr.Product.read_bitmask_raster()` method of the `epr.Product` class:

            product.read_bitmask_raster(bm_expr, offset_x, offset_y, bm_raster)

The `epr.Product.read_bitmask_raster()` method receives in input the bm_expr parameter that is set via command line:

        bm_expr = argv[2]

bm_expr is a string that define the logical expression for the definition of the bit-mask. In a bit-mask expression, any number of the flag-names (found in the DDDB) can be composed with “(”, ”)”, “NOT”, “AND”, “OR”.

Valid bit-mask expression are for example:

    flags.LAND OR flags.CLOUD

or:

    NOT flags.WATER AND flags.TURBID_S

Finally data are written to disk as a flat binary file using the `numpy.ndarray.tofile()` method of the `epr.Raster.data` attribute of the `epr.Raster` objects that exposes data via the `numpy.ndarray` interface:

            with open(image_file_path, 'wb') as out_stream:
                bm_raster.data.tofile(out_stream)

### Navigation

- index
- next |
- previous |
- PyEPR 0.8.1 documentation »
- Tutorials »