Repository files navigation

SarPy is a basic Python library to read, write, and do simple processingof complex SAR data using the NGA SICD format(standards linked below).It has been released by NGA to encourage the use of SAR data standardsthroughout the international SAR community. SarPy complements theSIX library (C++) and theMATLAB SAR Toolbox, which areimplemented in other languages but have similar goals.

Some sample SICD files can be foundhere.

A variety of SAR format standard are mentioned throughout this ReadMe, here areassociated references.

Sensor Independent Complex Data (SICD) - latest version (1.3.0; 2021-11-30)

1. Volume 1, Design & Implementation Description Document
2. Volume 2, File Format Description Document
3. Volume 3, Image Projections Description Document
4. Schema

Sensor Independent Derived Data (SIDD) - latest version (3.0; 2021-11-30)

1. Volume 1, Design and Implementation Description Document
2. Volume 2, NITF File Format Description Document
3. Volume 3, GeoTIFF File Format Description Document
4. Schema

Compensated Phase History Data (CPHD) - latest version (1.1.0; 2021-11-30)

1. Design & Implementation Description
2. Design & Implementation Schema

Both SICD and SIDD files are NITF files following specific guidelinesBasic Image Interchange Format (BIFF) - latest edition (2021.2; 2021-04-20)

1. National Imagery Transmission Format

For other NGA standards inquiries, the standards registry can be searched

here.

The basic capabilities provided in SarPy is generally SAR specific, and largelygeared towards reading and manipulating data provided in NGA SAR file formats.Full support for reading and writing SICD, SIDD, CPHD, and CRSD (standard pending)and associated metadata structures is currently provided, and this is the mainfocus of this project.

There is additionally support for reading data from complex data formats analogousto SICD format,usually called Single Look Complex (SLC) or Level 1, from avariety of commercial or other sources including

• Capella (partial support)
• COSMO-SkyMed (1st and 2nd generation)
• GFF (Sandia format)
• ICEYE
• NISAR
• PALSAR2
• RadarSat-2
• Radar Constellation Mission (RCM)
• Sentinel-1
• TerraSAR-X.

For this SLC format data, it is read directly as though it were coming from a SICDfile.This ability to read does not generally apply to data products otherthan the SLC or Level 1 product, and there is typically no direct NGA standardanalog for these products.

Some general TIFF and NITF reading support is provided, but this is not the maingoal of the SarPy library.

Documentation for the project is available atreadthedocs.

If this documentation is inaccessible, it can be built locally after checking outthis repository using sphinx via the commandpython setup.py build_sphinx.This depends on python packagesphinx.

SarPy was developed at the National Geospatial-Intelligence Agency (NGA). Thesoftware use, modification, and distribution rights are stipulated within theMIT license.

The core library functionality depends only onnumpy andscipy.

There are a small collection of dependencies representing functionality which maynot be core requirements for much of the sarpy targeted tasks. The tension betweenrequiring the least extensive list of dependencies possible for core functionalityand not having surprise unstated dependencies which caused unexpected failures isevident here. It is evident that there are many viable arguments for making anyor all of these formally stated dependencies. The choices made here are guided bypractical realities versus what is generally considered best practices.

For all packages on this list, the import is tried (where relevant), and anyimport errors for these optional dependencies are caught and handled. In other words,a missing optional dependencywill not be presented as import time. Exceptingthe functionality requiringh5py, this import error handling is probably silent.

Every module in sarpy can be successfully imported, provided that numpy and scipyare in the environment. Attempts at using functionality depending on a missingoptional dependency will generate an errorat run time with accompanyingmessage indicating the missing optional dependency.

• Support for reading single look complex data from certain sources which providedata in hdf5 format require theh5py package, this includes Cosmo-Skymed, ICEYE,and NISAR data.

• Reading an image segment in a NITF file using jpeg or jpeg 2000 compression,reading a GeoTIFF DEM, and/or writing a kmz image overlay requires thepillowpackage.

• CPHD consistency checks, presented in thesarpy.consistency module, depend onlxml>=4.1.1,networkx>=2.5,shapely>=1.6.4, andpytest>=3.3.2. Note that theseare the versions tested for compliance.

• Some less commonly used (in the sarpy realm) NITF functionality requires the useand interpretation of UTM coordinates, and this requires thepyproj package.

• Building sphinx documentation (mentioned below) requires packagessphinx,andsphinx_gallery.

• Optional portions of running unit tests (unlikely to be of relevance to anyonenot performing development on the core sarpy package itself) require thelxmlpackage

From PyPI, install using pip (may require escalated privileges e.g. sudo):

pip install sarpy

Note that herepip represents the pip utility for the desired Python environment.

For verbose instructions for installing from source, seehere. It is recommended thatstill the package is built locally and installed using pip, which allows a properpackage update mechanism, whilepython setup.py installdoes not.

Support for Python 2 has been dropped. The core sarpy functionality has beentested for Python 3.8, 3.9, 3.10, 3.11, 3.12.

Changes to sarpy for the sole purpose of supporting a Python version beyondend-of-life are unlikely to be considered.

Information regarding any discovered bugs would be greatly appreciated, so pleasefeel free to create a GitHub issue. If more appropriate, contactrichard.m.naething@nga.mil.

Integration branches (branches prefixed withintegration/) are used to stage content underconsideration for inclusion in themaster branch and future SarPy releases.These branches can be used to access features and bug fixes that have not been fully released.

Efforts at direct contribution to the project are certainly welcome, and pleasefeel free to make a pull request. Pull requests should be authored against themasterbranch but may be retargeted to a suitable integration branch upon review.Note that any and all contributions to this project will be released under the MIT license.

Software source code previously released under an open source license and thenmodified by NGA staff is considered a "joint work" (see 17 USC 101); it is partiallycopyrighted, partially public domain, and as a whole is protected by the copyrightsof the non-government authors and must be released according to the terms of theoriginal open source license.

Some associated SAR specific graphical user interface tools are maintained in thesarpy_apps project.