Extracting data on a specific region¶

The main aim of this library is to facilitate the extraction of knowledge over a specific region at the lunar surface. For the moment, only topography and images are available but more should come in the future.

This module is composed of three different class which I briefly detail in the following.

BinaryTable¶

This class allows to read binary file from the PDS site to retrieve the desired information.

The different possible binary files are all the ldem files listed here LRO/LOLA ldem for topography and all the images listed here LROC/WAC wac for WAC images.

For instance, if you want to read the information contained in ldem_512_90s_45s_090_180.img, simply load it in a variable called ldem here for the example:

from PDS_Extractor import BinaryTable
ldem = BinaryTable('ldem_16')

If the file is not already on your computer, the program is going to ask if you want to download it on the fly. Be careful with the size of high resolution image though, the download can take a few minutes !

When creating the object, the class store information contained in the header, either a separate .lbl file for files on the LRO/LOLA ldem or contained in the .img file for files on the LROC/WAC wac. All information can be access as attribute of the object.

However, the class does not load the data contained in the image during initialization. PDS images can be very large and resolution higher than 16 pixel per degree (ppd) usually do not fit into memory if you want to load the full image.

In agreement, the class proposed two methods to extract the data:

extract_all which extract the whole image. Again, make sure that information will fit into your computer memory.

extract_grid which extract the data contained in a window defined by its latitude/longitude boundaries.

In addition, the class proposed two methods than can give the latitude/longitude boundaries given a center long/lat point and a radius:

lambert_window will return square Lambert Azimuthal equal area projection of the region and

cylindrical_window will return the simple cylindrical projection of the region.

For instance, taken the object ldem we have just created, we can ask to get the data covering a region centred at (120 E, 60S) spanning a radius of 5 km by simply taping:

boundary = ldem.lambert_window(5,-60,120)
X,Y,Z = ldem.extract_grid(*boundary)

By default, if the given regime boundaries end up outside of the map, the class will re-size them so that they correspond to the image boundary. This should not happen for resolution smaller than 64 ppd as each image contains the whole lunar surface though.

However, for large resolution, the lunar surface is cut off in many subregions, i.e. subimages of reasonable size and it can be annoying to identify which one is relevant for the particular region of interest.

For this reason, this module also integrated two other class, one specialized in the topography and one specialized for images, that should be preferred to BinaryTable.

WacMap¶

WacMap is class which handle the treatment of WAC images. Indeed, getting an image over a specific region at the lunar surface can be annoying, you have to:

Identify the region of interest.

Identify the relevant img file ( possibly multiple due to overlap).

Load the information about each img files to be able to read the binary record into it.

Extract the data from the binary record.

With WacMap, you basically only need to feed it an input region and a desired resolution, and it does all that work for you.

For instance, for an image with a resolution of 512 ppd centred centred at (120 E, 60S) spanning a radius of 20 km, I simply use:

from PDS_Extractor import WacMap
boundary = ldem.lambert_window(20,-60,120)
wac_image = WacMap(512,*boundary)
X,Y,Z = wac_image.image()

with X containing the array of longitude where data exist, Y the latitudes and Z the information about the wac image itself. If you want to take a rapid look, just try:

import matplotlib as plt
plt.imshow(Z)

LolaMap¶

Same for the topography !

Say we’d like to overlap our nice images with the topography to get a beautiful image to show off with, simply add:

from PDS_Extractor import LolaMap
ldem_image = LolaMap(512,*boundary)
Xl,Yl,Zl = ldem_image.Image()

Now, you can simply overlay Zl and Z to get it. While the PDS_Extractor is designed to facilitate the extraction of data (X,Y,Z) arrays, the library also contained a second module that you can also use if you want to make beautiful images Structure.

Index¶

class pdsimage.PDS_Extractor.BinaryTable(fname, path_pdsfile='/home/docs/checkouts/readthedocs.org/user_builds/pdsimage/envs/master/local/lib/python2.7/site-packages/pdsimage-1.1.2-py2.7.egg/pdsimage/PDS_FILES')¶

Bases: object

Class to read image binary file from the LRO experiment

For the moment, it can gather information about the topography (from LRO LOLA experiment) and texture (from the LRO WAC experiment). More information about the Lunar Reconnaissance Orbiter mission (LRO) can be found here

LRO LOLA - Informations can be found at LRO/LOLA website. In particular, the header, located in a separate file .LBL file, contains all the informations.

LROC WAC - Informations can be found at LROC/WAC website. In particular, HEADER in the binary file that contain all the information - Read with the module pvl module for informations about how the header is extracted directly from the file.

This class has a method able to download the images, though it might be better to download them before as it takes a lot of time, especially for large resolution.

Both are NASA PDS FILE - Meaning, they are binary table whose format depends on the file. All the information can be found in the Header whose reference are above. Line usualy index latitude while sample on the line refers to longitude.

THIS CLASS SUPPORT ONLY CYLINDRICAL PROJECTION FOR THE MOMENT. PROJECTION : [WAC : ‘EQUIRECTANGULAR’, LOLA : ‘“SIMPLE”’] FURTHER WORK IS NEEDED FOR IT TO BECOMES MORE GENERAL.

Parameters:	fname (str) – Name of the image. path_pdsfiles (Optional[str]) – Path where the pds files are stored. Defaults, the path is set to the folder `PDS_FILES` next to the module files where the library is install. See `defaut_pdsfile` variable of the class

fname¶: str – Name of the image.

path_pdsfiles¶: str – path where the pds files are stored.

lolapath¶: str – path for LOLA images

wacpath¶: str – path for WAC images

grid¶: str – WAC or LOLA

img¶: str – name of the image

lbl¶: str – name of the lbl file, where information are stored. Empty for WAC.

Note

It is important to respect the structure of the PDS_FILES folder. It should contain 2 subfolder called LOLA and LROC_WAC where the corresponding images should be download.

I also integrate all the specification of the image contained in the header or the .LBL file as attribute of the class. However, the list is long and I do not introduce them into the documentation. See the file directly for details.

The abreaviations correspond to:

LRO Lunar Reconnaissance Orbiter
LOLA Lunar Orbiter Laser Altimeter
LROC Lunar Reconnaissance Orbiter Camera
WAC Wide Angle Camera

array(size_chunk, start, bytesize)¶

Read part of the binary file

Parameters:	size_chunk (int) – Size of the chunk to read start (int) – Starting byte bytesize (int) – Ending byte
Returns:	array of the corresponding values
Return type:	(np.array)

boundary()¶

Get the image boundary

Returns:	A tupple composed by the westernmost_longitude, the westernmost_longitude, the minimum_latitude and the maximum_latitude.

cylindrical_window(radius, lat0, long0)¶

Cylindrical projection of a window centered at (lat0, long0) with a given radius (km).

Parameters:	radius (float) – Radius of the window (km). lat0 (float) – Latitude at the center (degree). long0 (float) – Longitude at the center (degree).
Returns:	A tuple `(longll, longtr, latll, lattr)` with `longll` the longitude of the lower left corner, `longtr` the longitude of the top right corner, `latll` the latitude of the lower left corner and `lattr` the latitude of the top right corner.

Note

All return coordinates are in degree

defaut_pdsfile = '/home/docs/checkouts/readthedocs.org/user_builds/pdsimage/envs/master/local/lib/python2.7/site-packages/pdsimage-1.1.2-py2.7.egg/pdsimage/PDS_FILES'¶

extract_all()¶

Extract all the image

Returns:	A tupple of three arrays `(X,Y,Z)` with `X` contains the longitudes, `Y` contains the latitude and `Z` the values extracted from the image.

Note

All return arrays have the same size.

All coordinate are in degree.

extract_grid(longmin, longmax, latmin, latmax)¶

Extract part of the image img

Parameters:	longmin (float) – Minimum longitude of the window longmax (float) – Maximum longitude of the window latmin (float) – Minimum latitude of the window latmax (float) – Maximum latitude of the window
Returns:	A tupple of three arrays `(X,Y,Z)` with `X` contains the longitudes, `Y` contains the latitude and `Z` the values extracted from the window.

Note

All return arrays have the same size.

All coordinate are in degree.

lambert_window(radius, lat0, long0)¶

Square Lambert Azimuthal equal area projection of a window centered at (lat0, long0) with a given radius (km).

Parameters:	radius (float) – Radius of the window (km). lat0 (float) – Latitude at the center (degree). long0 (float) – Longitude at the center (degree).
Returns:	A tuple (longll, longtr, latll, lattr)` with ``longll the longitude of the lower left corner, `longtr` the longitude of the top right corner, `latll` the latitude of the lower left corner and `lattr` the latitude of the top right corner.

Note

All return coordinates are in degree

lat_id(line)¶

Return the corresponding latitude

Parameters:	line (int) – Line number
Returns:	Correponding latitude in degree

line_id(lat)¶

Return the corresponding line

Parameters:	lat (int) – latitude in degree
Returns:	Correponding line

long_id(sample)¶

Return the corresponding longitude

Parameters:	sample (int) – sample number on a line
Returns:	Correponding longidude in degree

sample_id(lon)¶

Return the corresponding sample

Parameters:	lon (int) – longidute in degree
Returns:	Correponding sample

class pdsimage.PDS_Extractor.LolaMap(ppd, lonm, lonM, latm, latM, path_pdsfile='/home/docs/checkouts/readthedocs.org/user_builds/pdsimage/envs/master/local/lib/python2.7/site-packages/pdsimage-1.1.2-py2.7.egg/pdsimage/PDS_FILES')¶

Bases: pdsimage.PDS_Extractor.WacMap

Class to handle the creation of LRO LOLA images

This class is specifically designed to handle the creation of image from LOLA images. It is able to identify the image (or the groupe of images) necessary to extract an array over a given window. Four cases are possible and taken care of:

The desired structure is entirely contained into one image.
The span in latitude of the image is ok but not longitudes(2 images).
The span in longitude of the image is ok but not latitudes (2 images).
Both latitude and longitude are not contained in one image(4 images).

Parameters:

ppd (int) – Required resolution
lonm (float) – Lower left window longitude (degree)
lonM (float) – Upper right window longitude (degree)
latm (float) – Lower left window latitude (degree)
latM (float) – Upper right window latitude (degree)
path_pdsfiles (Optional[str]) –
Path where the pds files are stored. Defaults, the path is set to the folder PDS_FILES next to the module files where the library is install.

See defaut_pdsfile variable of the class

ppd¶: int – Required resolution

lonm¶: float – Lower left window longitude (degree)

lonM¶: float – Upper right window longitude (degree)

latm¶: float – Lower left window latitude (degree)

latM¶: float – Upper right window latitude (degree)

path_pdsfiles¶: str – Path where the pds_files are stored.

Note

It is important to respect the structure of the PDS_FILES folder. WAC images should be contained within a subfolder called LROC_WAC.

Possible resolution are stored in the class variable implemented_res. Longitude in the code spans 0 to 360.

The abreviations correspond to:

LRO Lunar Reconnaissance Orbiter
LOLA Lunar Orbiter Laser Altimeter

Example

This class allows to simply gather three arrays X, Y, Z given a specific window. For instance, if we want to gather the data for a window which span 10 to 20 degree in longitude and the same in latitude, simply ask.

>>> X, Y, Z = LolaMap(512,10,20,10,20).image()

implemented_res = [4, 16, 64, 128, 256, 512, 1024]¶

class pdsimage.PDS_Extractor.WacMap(ppd, lonm, lonM, latm, latM, path_pdsfile='/home/docs/checkouts/readthedocs.org/user_builds/pdsimage/envs/master/local/lib/python2.7/site-packages/pdsimage-1.1.2-py2.7.egg/pdsimage/PDS_FILES')¶

Bases: object

Class to handle the creation of LROC WAC GLOBAL images

This class is specifically designed to handle the creation of image from LROC WAC images. It is able to identify the image (or the groupe of images) necessary to extract an array over a given window. Four cases are possible and taken care of:

The desired structure is entirely contained into one image.
The span in latitude of the image is ok but not longitudes(2 images).
The span in longitude of the image is ok but not latitudes (2 images).
Both latitude and longitude are not contained in one image(4 images).

Parameters:

ppd (int) – Required resolution
lonm (float) – Lower left window longitude (degree)
lonM (float) – Upper right window longitude (degree)
latm (float) – Lower left window latitude (degree)
latM (float) – Upper right window latitude (degree)
path_pdsfiles (Optional[str]) –
Path where the pds files are stored. Defaults, the path is set to the folder PDS_FILES next to the module files where the library is install.

See defaut_pdsfile variable of the class

ppd¶: int – Required resolution

lonm¶: float – Lower left window longitude (degree)

lonM¶: float – Upper right window longitude (degree)

latm¶: float – Lower left window latitude (degree)

latM¶: float – Upper right window latitude (degree)

path_pdsfiles¶: str – Path where the pds_files are stored.

Note

It is important to respect the structure of the PDS_FILES folder. WAC images should be contained within a subfolder called LROC_WAC.

Possible resolution are stored in the class variable implemented_res. Longitude in the code spans 0 to 360.

The abreaviations correspond to:

LROC Lunar Reconnaissance Orbiter Camera
WAC Wide Angle Camera

Example

This class allows to simply gather three arrays X, Y, Z given a specific window. For instance, if we want to gather the data for a window which spans 10 to 20 degree in longitude and the same in latitude, simply ask.

>>> X, Y, Z = WacMap(512,10,20,10,20).image()

defaut_pdsfile = '/home/docs/checkouts/readthedocs.org/user_builds/pdsimage/envs/master/local/lib/python2.7/site-packages/pdsimage-1.1.2-py2.7.egg/pdsimage/PDS_FILES'¶

image()¶

Return the values over the required window

Returns:	A tupple of three arrays `(X,Y,Z)` with `X` contains the longitudes, `Y` contains the latitude and `Z` the values extracted over the window.

Note

All return arrays have the same size.

All coordinates are in degree.

implemented_res = [4, 8, 16, 32, 64, 128, 256]¶