auromat.mapping.mapping module¶

This module provides core classes to handle georeferenced images. Most classes are base classes which are inherited from in other modules of this package.

class auromat.mapping.mapping.ArrayImageMixin(img)[source]¶

Bases: auromat.mapping.mapping.DefaultRGBMixin

Mixin for use with BaseMapping. Interprets an 8 bit (uint8) or 16 bit (uint16) 3-channel array as RGB image with the channels in RGB order.

img¶: Masked array of shape (h,w,n) and type (u)int.

img_unmasked¶

Like img but as a normal numpy array (not a masked array).

The purpose of this property (compared to img.data) is to implement more efficient ways to access the image data, in the case that the coordinates (lat, lon, etc.) are not needed. These would be calculated to properly mask the image.

class auromat.mapping.mapping.BaseMapping(altitude, cameraPosGCRS, photoTime, identifier, metadata=None)[source]¶

Bases: object

Base class for all mapping objects. Describes a georeferenced image for a given altitude.

The following assertions always hold: If a pixel in img is defined, then it is guaranteed that the corresponding center and corner coordinates are defined, as well as the elevation. If a pixel in img is NOT defined, then the corresponding center coordinate and elevation are also not defined; one of its corner coordinates may be defined in case a neighbouring pixel is defined, otherwise it is not defined.

More formally:

If lats[y,x] is not masked, then lons[y,x] is not masked, and vice versa.
If latsCenter[y,x] is not masked, then lonsCenter[y,x] is not masked, and vice versa.
If lats[y,x] is not masked, then at least one of latsCenter[y,x], latsCenter[y,x-1], latsCenter[y-1,x-1] or latsCenter[y-1,x] is not masked.
If latsCenter[y,x] is not masked, then lats[y,x], lats[y+1,x], lats[y+1,x+1] and lats[y,x+1] are not masked.
If img[y,x] is not masked, then latsCenter[y,x] is not masked, and vice versa.
If elevation[y,x] is not masked, then latsCenter[y,x] is not masked, and vice versa.

Parameters:

altitude (number) – the altitude in km onto which the image is mapped
cameraPosGCRS (array-like) – [x,y,z] camera position in GCRS coordinates, in km
photoTime (datetime.datetime) – date the photo was taken
identifier (str) – a string which uniquely names this mapping (e.g. ISS030-E-84614); it must be usable for parts of a filename
metadata (dict) – a flat dictionary of informational metadata that is used when exporting a mapping

altitude¶: Mapping altitude in km.

arcSecPerPx¶

Min, max, median, and mean angular sizes of pixels/polygons determined for the width, height, and diagonal of 1000 polygons.

Return type:	PixelScales

boundingBox¶: In case containsPole is True, this bounding box is degenerate! It will span the full longitude range in this case.

cameraFootpoint¶

The camera footpoint in geodetic coordinates.

Return type:	auromat.coordinates.geodesic.Location

cameraPosGCRS¶

centroid¶

The centroid of the mapping based on the plate-carree projection.

Return type:	auromat.coordinates.geodesic.Location

checkGuarantees()[source]¶

Checks if the guarantees defined for coordinate and data arrays are fulfilled. See the docstring of this class.

Note: This method is meant only for testing purposes.

checkPlateCarree()[source]¶: Raises an error when the latitude/longitude arrays do not describe a plate carree projection (regular grid).

containsDiscontinuity¶: Return whether the bounding box contains the discontinuity.

containsPole¶: Return whether the bounding box contains a pole.

createMasked(centerMask)[source]¶

Return a copy of this mapping with the given mask applied to img, latsCenter, lonsCenter, and elevation. Implementing classes must override this method and handle the lats and lons attributes and possible others. See maskedByElevation() for an application of this method.

Parameters:	centerMask – the mask is not copied and should not be used after anymore after calling this method

createResampled(lats, lons, latsCenter, lonsCenter, elevation, img)[source]¶

Returns a new mapping object with the given values. Each subclass can decide what the most appropriate class for the resampled data is. E.g. ThemisMapping uses itself, while AstrometryMapping uses GenericMapping. This is important as only the original class knows how to interpret the img data (if it’s not standard RGB in the case of THEMIS). See auromat.resample.resample() for an application of this method.

Parameters:	elevation – can be None

elevation¶: Elevation in degrees for each pixel center, that is, a masked array of shape (img.shape[0], img.shape[1]).

identifier¶

Return type:	str

img¶: Masked array of shape (h,w,n) and type (u)int.

img_unmasked¶

Like img but as a normal numpy array (not a masked array).

The purpose of this property (compared to img.data) is to implement more efficient ways to access the image data, in the case that the coordinates (lat, lon, etc.) are not needed. These would be calculated to properly mask the image.

isPlateCarree¶: Return whether the latitude/longitude arrays describe a plate carree projection (regular grid).

lats¶: A masked array of shape (img.shape[0]+1, img.shape[1]+1) containing the latitude of every pixel corner.

latsCenter¶: A masked array of shape shape (img.shape[0], img.shape[1]) containing the latitude of every pixel center.

lons¶: A masked array of shape shape (img.shape[0]+1, img.shape[1]+1) containing the longitude of every pixel corner.

lonsCenter¶: A masked array of shape (img.shape[0], img.shape[1]) containing the longitude of every pixel center.

mLatMlt¶

Tuple of masked arrays of the geomagnetic latitude/magnetic local time of every pixel corner.

Return type:	tuple(mlat, mlt) with array shape (img.shape[0]+1, img.shape[1]+1).

mLatMltCenter¶

Tuple of masked arrays of the geomagnetic latitude/magnetic local time of every pixel center.

Return type:	tuple(mlat, mlt) with shape (img.shape[0], img.shape[1]).

maskedByElevation(minElevation=10)[source]¶

Return a new mapping with data masked below the given minimum elevation. A previously applied mask is ignored.

Note that the new mapping reuses the existing arrays and just exchanges the masks.

Parameters:	minElevation (int) – 0 to 90, in degrees
Return type:	BaseMapping

maskedByPolygon(polygon)[source]¶

Returns a copy of this mapping where the image is masked using the given polygon. Only those pixels are retained where all of its corners are inside the polygon. A previously applied mask is ignored.

Note that the new mapping reuses the existing arrays and just exchanges the masks.

Warning

If the mapping or the polygon contains the discontinuity and/or poles then this method tries to handle it in a best-effort approach. It may happen that this approach fails where the resulting mapping could contain invalid data.

Parameters:	polygon (array-like) – ordered points of an unclosed polygon in [lat,lon] order
Return type:	BaseMapping

metadata¶

Return type:	dict

outline¶: The complete outline of this mapping. Note that the outline can be concave.

outlineConvexHull¶: The convex hull of the regular outline.

photoTime¶

Return type:	datetime.datetime

properties¶

Return information about the mapping as a named tuple.

Return type:	MappingProperties

rgb¶

A representation of img as a masked (h,w,3) uint8 RGB image with a range [0,255].

This is a convenience property for easy display of the image data.

This array shall never be modified directly, only through the underlying img.

Note to implementers: If this property is cached then care must be taken when a mapping gets masked. For example, when implementing createMasked() then the cache may be invalidated.

rgb_unmasked¶

Like rgb but as a normal numpy array (not a masked array).

The purpose of this property (compared to rgb.data) is to implement more efficient ways to access the image data, in the case that the coordinates (lat, lon, etc.) are not needed. These would be calculated to properly mask the image.

setDirty()[source]¶: Sets all values of cached properties to None so that they are recalculated the next time they are accessed.

class auromat.mapping.mapping.BaseMappingProvider(maxTimeOffset)[source]¶

Bases: object

Base class for all mapping providers.

Parameters:	maxTimeOffset – in seconds

contains(date)[source]¶

Return True if there is a mapping for the given date within +-maxTimeOffset.

Parameters:	date (datetime) –
Return type:	bool

containsAny(dates)[source]¶

Return True if there is a mapping for at least one of the given dates within +-maxTimeOffset.

Parameters:	dates – list of datetime objects
Return type:	bool

get(date)[source]¶

Returns the mapping which is closest to the given date within +-maxTimeOffset.

Raises ValueError:
Parameters:	date (datetime) –
Return type:	BaseMapping or MappingCollection
	when no mapping exists for the given date

getById(identifier)[source]¶

Returns the mapping with the given identifier.

Raises ValueError:
Parameters:	identifier (string) –
Return type:	BaseMapping or MappingCollection
	when no mapping with the given identifier exists

getSequence(dateBegin=None, dateEnd=None)[source]¶

Returns a generator of mappings ordered by date for the given date range. If dateBegin and dateEnd are None, then all available mappings are returned.

Parameters:	dateBegin (datetime) – dateEnd (datetime) – inclusive
Return type:	list of BaseMapping or MappingCollection objects

range¶

The dates of the first and last available mappings.

Return type:	datetime tuple (from, to)

class auromat.mapping.mapping.BoundingBox(latSouth, lonWest, latNorth, lonEast)[source]¶

Bases: object

Describes a geographical bounding box that can span across the discontinuity.

Parameters:	latSouth (number) – in degrees [-90,90] lonWest (number) – in degrees [-180,180] latNorth (number) – in degrees [-90,90] lonEast (number) – in degrees [-180,180]

bottomLeft¶

South west corner of the bounding box.

Return type:	auromat.coordinates.geodesic.Location

bottomRight¶

South east corner of the bounding box.

Return type:	auromat.coordinates.geodesic.Location

center¶

Center of the minimum spherical rectangle that fits the bounding box.

Return type:	auromat.coordinates.geodesic.Location

containsDiscontinuity¶

Return whether the bounding box contains the 180 degree discontinuity.

Return type:	bool

containsPole¶

Return whether the bounding box contains the north and/or south pole.

Return type:	bool

latNorth¶

latSouth¶

lonEast¶

lonWest¶

static mergedBoundingBoxes(boundingBoxes)[source]¶

Return the smallest bounding box that contains all given bounding boxes.

Parameters:	boundingBoxes – iterable of BoundingBox instances
Return type:	BoundingBox

static minimumBoundingBox(latLons)[source]¶

Return the smallest bounding box that contains all given coordinates.

Parameters:	latLons – iterable of (lat,lon) pairs
Return type:	BoundingBox

size¶

Width and height in km of the minimum spherical rectangle that fits the bounding box.

Note that the size is only correct if the bounding box spans less than 180 degrees in longitude.

Return type:	Size

topLeft¶

North west corner of the bounding box.

Return type:	auromat.coordinates.geodesic.Location

topRight¶

North east corner of the bounding box.

Return type:	auromat.coordinates.geodesic.Location

class auromat.mapping.mapping.DefaultRGBMixin[source]¶

Bases: object

Mixin for use with BaseMapping. Interprets an 8 bit (uint8) or 16 bit (uint16) 3-channel image as RGB image with the channels in RGB order.

rgb¶

A representation of img as a masked (h,w,3) uint8 RGB image with a range [0,255].

This is a convenience property for easy display of the image data.

This array shall never be modified directly, only through the underlying img.

Note to implementers: If this property is cached then care must be taken when a mapping gets masked. For example, when implementing createMasked() then the cache may be invalidated.

rgb_unmasked¶

Like rgb but as a normal numpy array (not a masked array).

The purpose of this property (compared to rgb.data) is to implement more efficient ways to access the image data, in the case that the coordinates (lat, lon, etc.) are not needed. These would be calculated to properly mask the image.

class auromat.mapping.mapping.FileImageMixin(imagePath)[source]¶

Bases: auromat.mapping.mapping.DefaultRGBMixin

Mixin for use with BaseMapping. Loads an 8 or 16 bit image file and converts it to an RGB image in case it is grayscale.

imagePath¶

img¶

img_unmasked¶

Like img but as a normal numpy array (not a masked array).

The purpose of this property (compared to img.data) is to implement more efficient ways to access the image data, in the case that the coordinates (lat, lon, etc.) are not needed. These would be calculated to properly mask the image.

class auromat.mapping.mapping.GenericMapping(lats, lons, latsCenter, lonsCenter, elev, alti, img, cameraPosGCRS, photoTime, identifier, metadata=None)[source]¶

Bases: auromat.mapping.mapping.GenericMapping

A mapping consisting of precalculated latitudes/longitudes/elevation values.

Parameters:

lats (ndarray) – (h+1,w+1) in degrees
lons (ndarray) – (h+1,w+1) in degrees
latsCenter (ndarray) – (h,w) in degrees
lonsCenter (ndarray) – (h,w) in degrees
elev (ndarray) – (h,w) in degrees; can also be None
alti (number) – the altitude in km onto which the image was mapped (e.g. 110)
img (ndarray) – uint8 or uint16 array of shape (h,w) for grayscale or (h,w,3) for RGB
cameraPosGCRS (array-like) – [x,y,z] in km
photoTime (datetime.datetime) –

createMasked(centerMask)¶

Return a copy of this mapping with the given mask applied to img, latsCenter, lonsCenter, and elevation. Implementing classes must override this method and handle the lats and lons attributes and possible others. See maskedByElevation() for an application of this method.

Parameters:	centerMask – the mask is not copied and should not be used after anymore after calling this method

elevation¶: Elevation in degrees for each pixel center, that is, a masked array of shape (img.shape[0], img.shape[1]).

img¶: Masked array of shape (h,w,n) and type (u)int.

lats¶: A masked array of shape (img.shape[0]+1, img.shape[1]+1) containing the latitude of every pixel corner.

latsCenter¶: A masked array of shape shape (img.shape[0], img.shape[1]) containing the latitude of every pixel center.

lons¶: A masked array of shape shape (img.shape[0]+1, img.shape[1]+1) containing the longitude of every pixel corner.

lonsCenter¶: A masked array of shape (img.shape[0], img.shape[1]) containing the longitude of every pixel center.

class auromat.mapping.mapping.MappingCollection(mappings, identifier, mayOverlap=True)[source]¶

Bases: object

A collection of mappings for the same photo time (+- a few seconds).

Parameters:

identifier (string) – e.g. THEMIS-2012.01.01.12.30.59
mayOverlap – True if some mappings may overlap each other This information is used for drawing polygons. When True, then the pixels of all mappings are joined together, sorted by elevation, and drawn in the same order (such that low-elevation polygons of one mapping are overdrawn by higher-elevation polygons of another overlapping mapping).

boundingBox¶: The smallest bounding box containing the bounding boxes of all mappings.

empty¶: Whether this collection contains no mappings.

identifier¶

mappings¶

maskedByElevation(minElevation=10)[source]¶

mayOverlap¶

photoTime¶: The median of the photo times of all mappings.

class auromat.mapping.mapping.MappingProperties¶

Bases: tuple

MappingProperties(altitude, cameraPosGCRS, boundingBox, photoTime, centroid, cameraFootpoint, identifier)

altitude¶: Alias for field number 0

boundingBox¶: Alias for field number 2

cameraFootpoint¶: Alias for field number 5

cameraPosGCRS¶: Alias for field number 1

centroid¶: Alias for field number 4

identifier¶: Alias for field number 6

photoTime¶: Alias for field number 3

auromat.mapping.mapping.MaskByElevationProvider(provider, *args, **kw)[source]¶

Wrap the given mapping provider by masking every returned mapping by elevation.

Parameters:	provider – the provider to wrap

See BaseMapping.maskedByElevation() for masking parameters.

class auromat.mapping.mapping.PixelScale¶

Bases: tuple

PixelScale(mean, median, min, max)

max¶: Alias for field number 3

mean¶: Alias for field number 0

median¶: Alias for field number 1

min¶: Alias for field number 2

class auromat.mapping.mapping.PixelScales¶

Bases: tuple

PixelScales(width, height, diagonal)

diagonal¶: Alias for field number 2

height¶: Alias for field number 1

width¶: Alias for field number 0

class auromat.mapping.mapping.Size¶

Bases: tuple

Size(width, height)

height¶: Alias for field number 1

width¶: Alias for field number 0

auromat.mapping.mapping.checkPlateCarree(lats, lons)[source]¶

Checks whether the given 2D coordinate arrays describe a plate carree projection, that is, if the latitudes (longitudes) are evenly spaced and monotonically decreasing (increasing).

Raises ValueError:
Parameters:	lats (ndarray) – 2D latitude array lons (ndarray) – 2D longitude array
	when the projection is not plate carree

auromat.mapping.mapping.convertMappingToSM(mapping)[source]¶

Return a new mapping with the coordinates transformed to solar magnetic latitudes and longitudes.

Warning

This function is not intended for regular use. If you need to access MLat/MLT coordinates, use the BaseMapping.mLatMlt and BaseMapping.mLatMltCenter attributes.

See auromat.draw.drawStereographicMLatMLT() for an application of this function.

Parameters:	mapping (BaseMapping) – A mapping where latitudes and longitudes are given in the standard geodetic coordinate system.
Return type:	BaseMapping

auromat.mapping.mapping.convertSMMappingToGeo(mapping)[source]¶: Inverse operation to convertMappingToSM().

auromat.mapping.mapping.inflatedEarthIntersection(cameraToPixelDirection, cameraPos, earthInflation=110, earthModel='wgs84')[source]¶

Return the intersection points with an inflated earth when shooting rays originating at cameraPos and going in the direction cameraToPixelDirection.

When earthModel is ‘sphere’ then the shape of the inflated earth is described by a sphere with radius earthRadius + earthInflation.

When earthModel is ‘wgs84’ then the shape of the inflated earth is described by an ellipsoid with an equatorial axis of wgs84A + earthInflation and a polar axis of wgs84B + earthInflation where wgs84A and wgs84B refers to the World Geodetic System 84.

Parameters:	cameraToPixelDirection – direction vectors in ICRS from camera location to pixel/sky location, shape (n,3) cameraPos – ndarray of xyz J2000 coordinates in km earthInflation – in km, how much to expand the earth when intersecting, use 0 for earth intersection earthModel – earth model, either ‘wgs84’ or ‘sphere’

auromat.mapping.mapping.isPlateCarree(lats, lons)[source]¶

Return whether the given 2D coordinate arrays describe a plate carree projection, that is, if the latitudes (longitudes) are evenly spaced and monotonically decreasing (increasing).

Parameters:	lats (ndarray) – 2D latitude array lons (ndarray) – 2D longitude array
Return type:	bool

auromat.mapping.mapping.sanitize_data(cls)[source]¶: A decorator for classes inheriting from BaseMapping. It lazily sanitizes data such that BaseMapping.checkGuarantees() is satisfied. This decorator assumes the most general case. If a more optimized sanitization technique can be implemented for a specific mapping class, then this should be done and this decorator not be used.