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 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232
|
API Reference
=============
.. module:: epr
:synopsis: Python bindings for ENVISAT Product Reader C API
PyEPR_ provides Python_ bindings for the ENVISAT Product Reader C API
(`EPR API`_) for reading satellite data from ENVISAT_ ESA_ (European
Space Agency) mission.
PyEPR_ is fully object oriented and, as well as the `EPR API`_ for C,
supports ENVISAT_ MERIS, AATSR Level 1B and Level 2 and also ASAR data
products. It provides access to the data either on a geophysical
(decoded, ready-to-use pixel samples) or on a raw data layer.
The raw data access makes it possible to read any data field contained
in a product file.
.. _PyEPR: https://github.com/avalentino/pyepr
.. _Python: http://www.python.org
.. _`EPR API`: https://github.com/bcdev/epr-api
.. _ENVISAT: http://envisat.esa.int
.. _ESA: http://earth.esa.int
.. currentmodule:: epr
Classes
-------
Product
~~~~~~~
.. class:: Product
ENVISAT product
The Product class provides methods and properties to get information
about an ENVISAT product file.
.. seealso:: :func:`open`
.. rubric:: Attributes
.. attribute:: file_path
The file's path including the file name
.. attribute:: id_string
The product identifier string obtained from the MPH parameter 'PRODUCT'
The first 10 characters of this string identify the product type,
e.g. "MER_1P__FR" for a MERIS Level 1b full resolution product.
The rest of the string decodes product instance properties.
.. attribute:: meris_iodd_version
For MERIS L1b and RR and FR to provide backward compatibility
.. attribute:: tot_size
The total size in bytes of the product file
.. rubric:: Methods
.. method:: get_band(name)
Gets the band corresponding to the specified name.
:param name:
the name of the band
:returns:
the requested :class:`Band` instance, or raises a
:exc:`EPRValueError` if not found
.. method:: get_band_at(index)
Gets the band at the specified position within the product
:param index:
the index identifying the position of the band, starting
with 0, must not be negative
:returns:
the requested :class:`Band` instance, or raises a
:exc:`EPRValueError` if not found
.. method:: get_dataset(name)
Gets the dataset corresponding to the specified dataset name
:param name:
the dataset name
:returns:
the requested :class:`Dataset` instance
.. method:: get_dataset_at(index)
Gets the dataset at the specified position within the product
:param index:
the index identifying the position of the dataset, starting
with 0, must not be negative
:returns:
the requested :class:`Dataset`
.. method:: get_dsd_at(index)
Gets the :class:`DSD` at the specified position
Gets the :class:`DSD` (dataset descriptor) at the specified
position within the product.
:param index:
the index identifying the position of the :class:`DSD`,
starting with 0, must not be negative
:returns:
the requested :class:`DSD` instance
.. method:: get_num_bands
Gets the number of all bands contained in a product
.. method:: get_num_datasets
Gets the number of all datasets contained in a product
.. method:: get_num_dsds
Gets the number of all :class:`DSD`\ s (dataset descriptors)
contained in the product
.. method:: get_scene_height
Gets the product's scene height in pixels
.. method:: get_scene_width
Gets the product's scene width in pixels
.. method:: get_mph
The :class:`Record` representing the main product header (MPH)
.. method:: get_sph
The :class:`Record` representing the specific product header (SPH)
.. method:: read_bitmask_raster(bm_expr, xoffset, yoffset, raster)
Calculates a bit-mask raster
Calculates a bit-mask, composed of flags of the given product
and combined as described in the given bit-mask expression, for
the a certain dimension and sub-sampling as defined in the
given raster.
:param bm_expr:
a string holding 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``
:param xoffset:
across-track co-ordinate in pixel co-ordinates (zero-based)
of the upper right corner of the source-region
:param yoffset:
along-track co-ordinate in pixel co-ordinates (zero-based)
of the upper right corner of the source-region
:param raster:
the raster for the bit-mask. The data type of the raster
must be either :data:`E_TID_UCHAR` or :data:`E_TID_CHAR`
:returns:
zero for success, an error code otherwise
.. seealso:: :func:`create_bitmask_raster`
.. method:: close
Closes the :class:`Product` product and free the underlying
file descriptor.
This method has no effect if the :class:`Product` is already
closed. Once the :class:`Product` is closed, any operation on
it will raise a ValueError.
As a convenience, it is allowed to call this method more than
once; only the first call, however, will have an effect.
.. rubric:: High level interface methods
.. note::
the following methods are part of the *high level* Python API and
do not have any correspondent function in the C API.
.. attribute:: closed
True if the :class:`Product` is closed.
.. method:: get_dataset_names
Return the list of names of the datasets in the product
.. method:: get_band_names
Return the list of names of the bands in the product
.. method:: datasets
Return the list of dataset in the product
.. method:: bands
Return the list of bands in the product
.. rubric:: Special methods
The :class:`Product` class provides a custom implementation of the
following *special methods*:
* __repr__
* __str__
* __enter__
* __exit__
Dataset
~~~~~~~
.. class:: Dataset
ENVISAT dataset
The Dataset class contains information about a dataset within an
ENVISAT product file which has been opened with the :func:`open`
function.
A new Dataset instance can be obtained with the
:meth:`Product.get_dataset` or :meth:`Product.get_dataset_at` methods.
.. rubric:: Attributes
.. attribute:: description
A short description of the band's contents
.. attribute:: product
The :class:`Product` instance to which this dataset belongs to
.. rubric:: Methods
.. method:: get_name
Gets the name of the dataset
.. method:: get_dsd
Gets the dataset descriptor (DSD)
.. method:: get_dsd_name
Gets the name of the DSD (dataset descriptor)
.. method:: get_num_records
Gets the number of records of the dataset
.. method:: create_record
Creates a new record
Creates a new, empty record with a structure compatible with
the dataset. Such a record is typically used in subsequent
calls to :meth:`Dataset.read_record`.
:returns:
the new record instance
.. method:: read_record(index[, record])
Reads specified record of the dataset
The record is identified through the given zero-based record
index. In order to reduce memory reallocation, a record
(pre-)created by the method :meth:`Dataset.create_record` can
be passed to this method.
Data is then read into this given record.
If no record (``None``) is given, the method initiates a new
one.
In both cases, the record in which the data is read into will
be returned.
:param index:
the zero-based record index
:param record:
a pre-created record to reduce memory reallocation, can be
``None`` (default) to let the function allocate a new
record
:returns:
the record in which the data has been read into or raises
an exception (:exc:`EPRValueError`) if an error occurred
.. rubric:: High level interface methods
.. note::
the following methods are part of the *high level* Python API and
do not have any correspondent function in the C API.
.. method:: records
Return the list of records contained in the dataset
.. rubric:: Special methods
The :class:`Dataset` class provides a custom implementation of the
following *special methods*:
* __repr__
* __str__
* __iter__
Record
~~~~~~
.. class:: Record
Represents a record read from an ENVISAT dataset
A record is composed of multiple fields.
.. seealso:: :class:`Field`
.. rubric:: Methods
.. method:: get_field(name)
Gets a field specified by name
The field is here identified through the given name.
It contains the field info and all corresponding values.
:param name:
the the name of required field
:returns:
the specified :class:`Field` or raises an exception
(:exc:`EPRValueError`) if an error occurred
.. method:: get_field_at(index)
Gets a field at the specified position within the record
:param index:
the zero-based index (position within record) of the field
:returns:
the field or raises and exception (:exc:`EPRValueError`)
if an error occurred
.. method:: get_num_fields
Gets the number of fields contained in the record
.. method:: print_([ostream])
Write the record to specified file (default: :data:`sys.stdout`)
This method writes formatted contents of the record to
specified *ostream* text file or (default) the ASCII output
is be printed to standard output (:data:`sys.stdout`)
:param ostream:
the (opened) output file object
.. note::
the *ostream* parameter have to be a *real* file not
a generic stream object like :class:`StringIO.StringIO`
instances
.. method:: print_element(field_index, element_index[, ostream])
Write the specified field element to file (default: :data:`sys.stdout`)
This method writes formatted contents of the specified field
element to the *ostream* text file or (default) the ASCII output
will be printed to standard output (:data:`sys.stdout`)
:param field_index:
the index of field in the record
:param element_index:
the index of element in the specified field
:param ostream:
the (opened) output file object
.. note::
the *ostream* parameter have to be a *real* file not
a generic stream object like :class:`StringIO.StringIO`
instances
.. rubric:: High level interface methods
.. note::
the following methods are part of the *high level* Python API and
do not have any correspondent function in the C API.
.. method:: get_field_names
Return the list of names of the fields in the product
.. method:: fields
Return the list of fields contained in the record
.. rubric:: Special methods
The :class:`Record` class provides a custom implementation of the
following *special methods*:
* __repr__
* __str__
* __iter__
Field
~~~~~
.. class:: Field
Represents a field within a record
A field is composed of one or more data elements of one of the
types defined in the internal ``field_info`` structure.
.. seealso:: :class:`Record`
.. method:: get_description
Gets the description of the field
.. method:: get_name
Gets the name of the field
.. method:: get_num_elems
Gets the number of elements of the field
.. method:: get_type
Gets the type of the field
.. method:: get_unit
Gets the unit of the field
.. method:: get_elem([index])
Field single element access
This function is for getting the elements of a field.
:param index:
the zero-based index of element to be returned, must not be
negative. Default: 0.
:returns:
the typed value from given field
.. method:: get_elems
Field array element access
This function is for getting an array of field elements of the
field.
:returns:
the data array (:class:`numpy.ndarray`) having the type of
the field
.. method:: print_([ostream])
Write the field to specified file (default: :data:`sys.stdout`)
This method writes formatted contents of the field to
specified *ostream* text file or (default) the ASCII output
is be printed to standard output (:data:`sys.stdout`)
:param ostream:
the (opened) output file object
.. note::
the *ostream* parameter have to be a *real* file not
a generic stream object like :class:`StringIO.StringIO`
instances
.. rubric:: Special methods
The :class:`Field` class provides a custom implementation of the
following *special methods*:
* __repr__
* __str__
* __eq__
* __ne__
* __len__ [#]_
.. rubric:: Footnotes
.. [#] if the field is a :data:`E_TID_STRING` field then the
:meth:`__len__` method returns the string length, otherwise the
number of elements of the field is returned (same as
:meth:`Field.get_num_elems`)
DSD
~~~
.. class:: DSD
Dataset descriptor
The DSD class contains information about the properties of a
dataset and its location within an ENVISAT product file
.. rubric:: Attributes
.. attribute:: ds_name
The dataset name
.. attribute:: ds_offset
The offset of dataset-information the product file
.. attribute:: ds_size
The size of dataset-information in dataset product file
.. attribute:: ds_type
The dataset type descriptor
.. attribute:: dsr_size
The size of dataset record for the given dataset name
.. attribute:: filename
The filename in the DDDB with the description of this dataset
.. attribute:: index
The index of this DSD (zero-based)
.. attribute:: num_dsr
The number of dataset records for the given dataset name
.. rubric:: Special methods
The :class:`DSD` class provides a custom implementation of the
following *special methods*:
* __repr__
* __eq__
* __ne__
Band
~~~~
.. class:: Band
The band of an ENVISAT product
The Band class contains information about a band within an ENVISAT
product file which has been opened with the :func:`open` function.
A new Band instance can be obtained with the :meth:`Product.get_band`
method.
.. rubric:: Attributes
.. attribute:: bm_expr
A bit-mask expression used to filter valid pixels
All others are set to zero
.. attribute:: data_type
The data type of the band's pixels
Possible values are:
* ``*`` --> the datatype remains unchanged.
* ``uint8_t`` --> 8-bit unsigned integer
* ``uint32_t`` --> 32-bit unsigned integer
* ``Float`` --> 32-bit IEEE floating point
.. attribute:: description
A short description of the band's contents
.. attribute:: lines_mirrored
Mirrored lines flag
If true (=1) lines will be mirrored (flipped) after read into a
raster in order to ensure a pixel ordering in raster X direction
from WEST to EAST.
.. attribute:: product
The :class:`Product` instance to which this band belongs to
.. attribute:: sample_model
The sample model operation
The sample model operation applied to the source dataset for
getting the correct samples from the MDS (for example MERIS L2).
Possible values are:
* ``*`` --> no operation (direct copy)
* ``1OF2`` --> first byte of 2-byte interleaved MDS
* ``2OF2`` --> second byte of 2-byte interleaved MDS
* ``0123`` --> combine 3-bytes interleaved to 4-byte integer
.. attribute:: scaling_factor
The scaling factor
Possible values are:
* ``*`` --> no factor provided (implies scaling_method=*)
* ``const`` --> a floating point constant
* ``GADS.field[.field2]`` --> value is provided in global
annotation dataset with name `GADS` in field `field``.
Optionally a second element index for multiple-element fields
can be given too
.. attribute:: scaling_method
The scaling method which must be applied to the raw source data
in order to get the 'real' pixel values in geo-physical units.
Possible values are:
* ``*`` --> no scaling applied
* ``Linear_Scale`` --> linear scaling applied::
y = offset + scale * x
* ``Log_Scale`` --> logarithmic scaling applied::
y = log10(offset + scale * x)
.. attribute:: scaling_offset
Possible values are:
* ``*`` --> no offset provided (implies scaling_method=*)
* ``const`` --> a floating point constant
* ``GADS.field[.field2]` --> value is provided in global
annotation dataset with name ``GADS`` in field ``field``.
Optionally a second element index for multiple-element fields
can be given too
.. attribute:: spectr_band_index
The (zero-based) spectral band index
-1 if this is not a spectral band
.. attribute:: unit
The geophysical unit for the band's pixel values
.. rubric:: Methods
.. method:: get_name
Gets the name of the band
.. method:: create_compatible_raster(src_width, src_height[, xstep, ystep])
Creates a raster which is compatible with the data type of the band
The created raster is used to read the data in it (see
:meth:`Band.read_raster`).
The raster is defined on the grid of the product, from which the
data are read. Spatial subsets and under-sampling are possible)
through the parameter of the method.
A raster is an object that allows direct access to data of a
certain portion of the ENVISAT product that are read into the it.
Such a portion is called the source. The complete ENVISAT product
can be much greater than the source. One can move the raster over
the complete ENVISAT product and read in turn different parts
(always of the size of the source) of it into the raster.
The source is specified by the parameters *height* and *width*.
A typical example is a processing in blocks. Lets say, a block
has 64x32 pixel. Then, my source has a width of 64 pixel and a
height of 32 pixel.
Another example is a processing of complete image lines. Then,
my source has a widths of the complete product (for example 1121
for a MERIS RR product), and a height of 1). One can loop over
all blocks read into the raster and process it.
In addition, it is possible to defined a sub-sampling step for
a raster. This means, that the source is not read 1:1 into the
raster, but that only every 2nd or 3rd pixel is read. This step
can be set differently for the across track (source_step_x) and
along track (source_step_y) directions.
:param src_width:
the width (across track dimension) of the source to be read
into the raster
:param src_height:
the height (along track dimension) of the source to be read
into the raster
:param xstep:
the sub-sampling step across track of the source when reading
into the raster. Default: 1.
:param ystep:
the sub-sampling step along track of the source when reading
into the raster. Default: 1.
:returns:
the new raster instance or raises an exception
(:exc:`EPRValueError`) if an error occurred
.. method:: read_raster([xoffset, yoffset, raster])
Reads (geo-)physical values of the band of the specified
source-region
The source-region is a defined part of the whole ENVISAT
product image, which shall be read into a raster.
In this routine the co-ordinates are specified, where the
source-region to be read starts.
The dimension of the region and the sub-sampling are attributes
of the raster into which the data are read.
:param xoffset:
across-track source co-ordinate in pixel co-ordinates
(zero-based) of the upper right corner of the source-region.
Default 0.
:param yoffset:
along-track source co-ordinate in pixel co-ordinates
(zero-based) of the upper right corner of the source-region.
Default 0.
:param raster:
:class:`Raster` instance set with appropriate parameters to
read into. If not provided a new :class:`Raster` is
instantiated
:returns:
the :class:`Raster` instance in which data are read
This method raises an instance of the appropriate
:exc:`EPRError` sub-class if case of errors
.. seealso:: :meth:`Band.create_compatible_raster` and
:func:`create_raster`
.. rubric:: High level interface methods
.. note::
the following methods are part of the *high level* Python API and
do not have any correspondent function in the C API.
.. method:: read_as_array([width, height, xoffset, yoffset, xstep, ystep])
Reads the specified source region as an :class:`numpy.ndarray`
The source-region is a defined part of the whole ENVISAT
product image, which shall be read into a raster.
In this routine the co-ordinates are specified, where the
source-region to be read starts.
The dimension of the region and the sub-sampling are attributes
of the raster into which the data are read.
:param src_width:
the width (across track dimension) of the source to be read
into the raster. If not provided reads as much as possible
:param src_height:
the height (along track dimension) of the source to be read
into the raster, If not provided reads as much as possible
:param xoffset:
across-track source co-ordinate in pixel co-ordinates
(zero-based) of the upper right corner of the source-region.
Default 0.
:param yoffset:
along-track source co-ordinate in pixel co-ordinates
(zero-based) of the upper right corner of the source-region.
Default 0.
:param xstep:
the sub-sampling step across track of the source when
reading into the raster. Default: 1
:param ystep:
the sub-sampling step along track of the source when
reading into the raster. Default: 1
:returns:
the :class:`numpy.ndarray` instance in which data are read
This method raises an instance of the appropriate
:exc:`EPRError` sub-class if case of errors
.. seealso:: :meth:`Band.create_compatible_raster`,
:func:`create_raster` and :meth:`Band.read_raster`
.. rubric:: Special methods
The :class:`Band` class provides a custom implementation of the
following *special methods*:
* __repr__
Raster
~~~~~~
.. class:: Raster
Represents a raster in which data will be stored
All 'size' parameter are in PIXEL.
.. rubric:: Attributes
.. attribute:: data_type
The data type of the band's pixels
All ``E_TID_*`` types are possible
.. attribute:: source_height
The height of the source
.. attribute:: source_width
The width of the source
.. attribute:: source_step_x
The sub-sampling for the across-track direction in pixel
.. attribute:: source_step_y
The sub-sampling for the along-track direction in pixel
.. rubric:: High level interface attributes
.. note::
the following attributess are part of the *high level* Python API and
do not have a counterpart in the C API.
.. attribute:: data
Raster data exposed as :class:`numpy.ndarray` object
.. note::
this property shares the data buffer with the :class:`Raster`
object so any change in its contents is also reflected to
the :class:`Raster` object
.. note::
the :class:`Raster` objects do not have a field named *data* in the
corresponding C structure. The *EPR_SRaster* C structure have a
field named *buffer* that is a raw pointer to the data buffer and
it is not exposed as such in the Python API.
.. rubric:: Methods
.. method:: get_pixel(x, y)
Single pixel access
This function is for getting the values of the elements of a
raster (i.e. pixel)
:param x:
the (zero-based) X coordinate of the pixel
:param y:
the (zero-based) Y coordinate of the pixel
:returns:
the typed value at the given co-ordinate
.. method:: get_elem_size
The size in byte of a single element (sample) of this raster's
buffer
.. method:: get_height
Gets the raster's height in pixels
.. method:: get_width
Gets the raster's width in pixels
.. rubric:: Special methods
The :class:`Raster` class provides a custom implementation of the
following *special methods*:
* __repr__
EPRTime
~~~~~~~
.. class:: EPRTime
Convenience class for time data exchange.
EPRTime is a :class:`collections.namedtuple` with the following fields:
.. attribute:: days
.. attribute:: seconds
.. attribute:: microseconds
Functions
---------
.. function:: open(filename)
Opens the ENVISAT product
Opens the ENVISAT product file with the given file path, reads MPH,
SPH and all DSDs, organized the table with parameter of line length
and tie points number.
:param product_file_path:
the path to the ENVISAT product file
:returns:
the :class:`Product` instance representing the specified
product. An exception (:exc:`exceptions.ValueError`) is raised
if the file could not be opened.
The :class:`Product` class supports context management so the recommended
way to ensure that a product is actually closed as soon as a task is
completed is to use the ``with`` statement::
with open('ASA_IMP_1PNUPA20060202_ ... _3110.N1') as product:
dataset = product.get_dataset('MAIN_PROCESSING_PARAMS_ADS')
record = dataset.read_record(0)
print(record)
.. seealso :class:`Product`
.. function:: data_type_id_to_str
Gets the 'C' data type string for the given data type
.. function:: get_data_type_size
Gets the size in bytes for an element of the given data type
.. function:: get_sample_model_name
Return the name of the specified sample model
.. function:: get_scaling_method_name
Return the name of the specified scaling method
.. function:: create_raster(data_type, src_width, src_height[, xstep, ystep])
Creates a raster of the specified data type
This function can be used to create any type of raster, e.g. for
later use as a bit-mask.
:param data_type:
the type of the data to stored in the raster, must be one of
E_TID_*.
.. seealso:: `Data type Identifiers`_
:param src_width:
the width (across track dimension) of the source to be read
into the raster.
See description of :meth:`Band.create_compatible_raster`
:param src_height:
the height (along track dimension) of the source to be read
into the raster.
See description of :meth:`Band.create_compatible_raster`
:param xstep:
the sub-sampling step across track of the source when reading
into the raster. Default: 1.
:param ystep:
the sub-sampling step along track of the source when reading
into the raster. Default: 1.
:returns:
the new :class:`Raster` instance
.. seealso:: description of :meth:`Band.create_compatible_raster`
.. function:: create_bitmask_raster(src_width, src_height[, xstep, ystep])
Creates a raster to be used for reading bitmasks
The raster returned always is of type ``byte``.
:param src_width:
the width (across track dimension) of the source to be read
into the raster
:param src_height:
the height (along track dimension) of the source to be read
into the raster
:param xstep:
the sub-sampling step across track of the source when reading
into the raster. Default: 1.
:param ystep:
the sub-sampling step along track of the source when reading
into the raster. Default: 1.
:returns:
the new raster instance or raises an exception
(:exc:`EPRValueError`) if an error occurred
.. seealso:: the description of :meth:`Band.create_compatible_raster`
Exceptions
----------
EPRError
~~~~~~~~
.. exception:: EPRError
EPR API error
.. attribute:: code
EPR API error code
.. method:: __init__([message[, code, *args, **kwargs]])
Initializer
:param message:
error message
:pram code:
EPR error code
EPRValueError
~~~~~~~~~~~~~
.. exception:: EPRValueError
Inherits both :exc:`EPRError` and standard :exc:`exceptions.ValueError`
Data
----
.. data:: __version__
Version string of PyEPR
.. data:: __revision__
PyEPR revision (currently it is the same as :data:`__version__`)
.. deprecated:: 7.2
.. data:: EPR_C_API_VERSION
Version string of the wrapped `EPR API`_ C library
Data type identifiers
~~~~~~~~~~~~~~~~~~~~~
.. data:: E_TID_UNKNOWN
.. data:: E_TID_UCHAR
.. data:: E_TID_CHAR
.. data:: E_TID_USHORT
.. data:: E_TID_SHORT
.. data:: E_TID_UINT
.. data:: E_TID_INT
.. data:: E_TID_FLOAT
.. data:: E_TID_DOUBLE
.. data:: E_TID_STRING
.. data:: E_TID_SPARE
.. data:: E_TID_TIME
Sample Models
~~~~~~~~~~~~~
.. data:: E_SMOD_1OF1
.. data:: E_SMOD_1OF2
.. data:: E_SMOD_2OF2
.. data:: E_SMOD_3TOI
.. data:: E_SMOD_2TOF
Scaling Methods
~~~~~~~~~~~~~~~
.. data:: E_SMID_NON
No scaling
.. data:: E_SMID_LIN
Linear pixel scaling
.. data:: E_SMID_LOG
Logarithmic pixel scaling
|