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
#!/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

'''

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 !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
    product = epr.open(product_file_path)

    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.

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

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.

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)

Project Versions

Previous topic

Exporting band data

Next topic

NDVI computation

This Page