htrdrPy.geometry module

class htrdrPy.geometry.Geometry(source=None, camera=None, image=None, volrad=None, case=None)[source]

Bases: object

htrdrPy.Geometry is a class that aims at managing all information related to the observation geometry. It handles the camera, source and image properties as well as the mesh on which running the volumic radiative budget calculations, if running on this mode.

The Geometry module handles the positioning, orientation and properties of the camera and source. The data can be provided directly when creating an instance as distinct dictionnaries for the source, the camera and the image, with the following keys:

Parameters:

  • source (dict, optional) –

    Dictionnary containing the information on the source, with the following keys:

    • ”longitude”float

      Longitude of the source [°].

    • ”latitude”float

      Latitude of the source [°].

    • ”distance” :

      Distance of the source [m].

    • ”radius”float

      Radius of the source [m].

    • ”temperature”float, optional

      Surface temperature of the source [K] (used to calculate the Planck’s function)

    • ”radiance”str, optional

      Path to a radiance file in htrdr readable format.

    • ”spectrum”numpy.ndarray, optional

      2-D array containing the spectrum (shape=(nWavelength,2)). The first column contains the wavelength [nm] and the second contains the radiance [W/m2/sr/nm]) at the surface of the source.

  • camera (dict, optional) –

    Dictionnary containing the information on the camera, with the following keys:

    • ”position”numpy.ndarray

      Position of the camera in cartesian coordinates (shape=(3), [m]). The origin corresponds to the center of the observed target.

    • ”target”numpy.ndarray

      Position of the target in cartesian coordinates (shape=(3), [m]). The origin corresponds to the center of the observed target. This is NOT the line of sight but the position vector of the target.

    • ”field of view”float

      Vertical field of view of the camera [°] (the horizontal field of view is calculated via scaling by the image aspect ratio, assuming square pixels).

    • ”roll”numpy.ndarray, optional

      Vector setting the upward direction of the camera (shape=(3), [m]) i.e. a vector in the pixel plane to turn the camera around the line of sight. If not provided, it is calculated as perpendicular to the line of sight and to z axis (or x axis if the z axis corresponds to the line of sight).

  • image (dict, optional) –

    Dictionnary containing the information on the image, with the following keys:

    • ”definition”array-like

      Definition (number of pixels) of the image (shape=(2), the first value is the horizontal number of pixel and the second value is the vertical pixel count).

    • ”sampling”int

      Number of rays to sample for each pixel.

exportGeometry()[source]

Export the geometry (source, camera and image data) in a geometry_{case}.json file stored in the “geometries/” repository

geometryFromAPIE(observation, distance, radius, cameraFOV, sourceDist, sourceRad, sourceTemp=None, radianceFile=None, spectrum=None)[source]

Calulate the observation geometry from Azimut, Phase, Incident and Emergent angles.

Parameters:

  • observation (dict) –

    Dictionnary containing the geometry of the observation with the following items:

    • ”azimut”float

      Angle between the projected incidence and the projected emergence [°].

    • ”phase”float

      Angle between incident rays (directly from the source) and the line of sight [°].

    • ”incidence”float

      Angle between the incident rays (directly from the source) and the normal to the ground at the observed loaction [°].

    • ”emergence”float

      Angle between the normal to the line of sight and the normal to the ground at the observed loaction [°].

  • distance (float) – Distance from the camera to the target [m].

  • radius (float) – Radius of the planet to locate the target on the surface [m].

  • cameraFOV (float) – Field of view of the camera (c.f. htrdrPy.Geometry.setCamera).

  • sourceDist (float) – Distance of the source [m] (c.f. htrdrPy.Geometry.setSource).

  • sourceRad (float) – Radius of the source [m] (c.f. htrdrPy.Geometry.setSource).

  • spectrum (float, optional) – Spectrum of the source (c.f. htrdrpy.geometry.setsource).

  • radianceFile (float, optional) – Path to the radiance file of the source (c.f. htrdrpy.geometry.setsource).

  • sourcetemp (float, optional) – Temperature of the source (c.f. htrdrpy.geometry.setsource).

plotGeometry(ax, radius)[source]

Plot the gometry: the observed planet, the line of sight (blue vector), the source direction (red vector), the camera plan (black vectors) and the field of view (green vectors).

Parameters:

  • ax (matplotlib.pyplot.Axes) – Axe on which draxing the plot. It must be a 3D axe.

  • radius (float) – Radius of the planet [m].

Warning

matplotlib.pyplot 3d projection has some issues with vector orientation. If they have the right direction, they may not have the right sens.

setCamera(position, targetPosition, fieldOfView, roll=None)[source]

Setup the camera position, orientation and field of view

Parameters:

  • position (numpy.ndarray) – Position of the camera in cartesian coordinates (shape=(3), [m]). The origin corresponds to the center of the observed target.

  • targetPosition (numpy.ndarray) – Position of the target in cartesian coordinates (shape=(3), [m]). The origin corresponds to the center of the observed target. This is NOT the line of sight but the position vector of the target.

  • fieldOfView (float) – Vertical field of view of the camera [°] (the horizontal field of view is calculated via scaling by the image aspect ratio, assuming square pixels).

  • roll (numpy.ndarray, optional) – Vector setting the upward direction of the camera (shape=(3), [m]) i.e. a vector in the pixel plane to turn the camera around the line of sight. If not provided, it is calculated as perpendicular to the line of sight and to z axis (or x axis if the z axis corresponds to the line of sight).

setImage(definition, sampling)[source]

Setup the image properties

Parameters:

  • definition" (array-like) – Definition (number of pixels) of the image (shape=(2), the first value is the horizontal number of pixel and the second value is the vertical pixel count).

  • sampling" (int) – Number of rays to sample for each pixel.

setSource(longitude, latitude, distance, radius, temperature=None, radianceFile=None, spectrum=None)[source]

Setup the source properties.

Parameters:

  • longitude (float) – Longitude of the source [°].

  • latitude (float) – Latitude of the source [°].

  • distance – Distance of the source [m].

  • radius (float) – Radius of the source [m].

  • temperature (float, optional) – Surface temperature of the source [K] (used to calculate the Planck’s function)

  • radianceFile (str, optional) – Path to a radiance file in htrdr readable format.

  • spectrum (numpy.ndarray, optional) – 2-D array containing the spectrum (shape=(nWavelength,2)). The first column contains the wavelength [nm] and the second contains the radiance [W/m2/sr/nm]) at the surface of the source.

Notes

Whereas temperature, radianceFile and spectrum are optional, at least one of those must be provided. If more than one is provided, the spectrum is taken in priority, then the radianceFile and finally the temperature.

setSpectralCumulDist(pdf, data=None)[source]

Setup the probability density function to used for sampling the wavelength and correlated-k coefficient.

Parameters:

pdf (numpy.ndarray) – Table containing the cumulative distribution used to sample the wavelength and k-coefficient (shape=(nAltitudes,nLatitudes,nLongitudes,nSpectralElements)). nSpectralElements correspond to nWavelength * nCoeff.

setVolrad(sampling, mesh='origin', args=None)[source]

Setup the volumic radiative budget properties. The volumic radiative budget mode evaluate the divergence of the flux within each provided tetrahedron. This method handles the generation of the mesh on which the calulation will be conducted.

Parameters:

  • sampling (int) – Number of ray to sample for each tetrahedron.

  • mesh ({"origin", "makeColumnPP", "makeFromCellCoord", "makeSliceAltLat", "extractFromData"}, default "origin") –

    Method to build the mesh on which the radiative budget calculation is realized.

    Building method

    ”origin”

    Use the original atmosphere mesh.

    ”makeColumnPP”

    Generate one plane-parallel column.

    ”makeFromCellCoord”

    Generate a complete sphere from a table of coordinates.

    ”makeSliceAltLat”

    Generate a slice in altitude / latitude from a table of coordinates.

    ”extractFromData”

    Extract a list of cells from an already generated mesh.

  • args (tuple) –

    Tuple containing the arguments required by the chosen mesh generation method.

    Arguments

    Method

    Required arguments

    ”origin”

    ”makeColumnPP”
    altitudesnumpy.ndarray

    Array continaing the altitudes [m], either at the center of the cells or at the boundaries (shape = nLevel or nLayer).

    hwidthfloat

    Horizontal dimension of the squared base column [m].

    centerbool, default: True

    True if the altitudes represent the cell centers and False if they correspond to the boundaries of the cells.

    ”makeFromCellCoord”
    cellCoordnumpy.ndarray

    Coordinates of the cells centers or cell interface centers (c.f. onLevels, shape=(nAltitudes,nLatitudes,nLongitudes,3), [m])

    radiusfloat

    Radius of the planet [m].

    polesbool, default False

    Whether or not the first and last latitudes correspond to the poles in the given array of coordinates.

    onLevelsbool, default False

    Whether or not the altitudes provided in the coordinates are given on the levels or in the center of the cells.

    ”makeSliceAltLat”
    cellCoordnumpy.ndarray

    Coordinates of the cells centers or cell interface centers (c.f. onLevels, shape=(nAltitudes,nLatitudes,3), [m])

    radiusfloat

    Radius of the planet [m].

    dLongitudefloat

    Longitude width of the slice [°].

    polesbool, default False

    Whether or not the first and last latitudes correspond to the poles in the given array of coordinates.

    onLevelsbool, default False

    Whether or not the altitudes provided in the coordinates are given on the levels or in the center of the cells.

    ”extractFromData”
    datahtrdrPy.Data or htrdrPy.Geometry

    Object instance containing an already generated mesh from which extracting the list of cells. This is non-desctructive for the original htrdrPy.Data or htrdrPy.Geometry and only affects the current instance that “steals” the wanted cells.

    cellsnumpy.ndarray

    Array of the cells to be extracted (shape=(nCell,3)) with the altitude, latitude and longitude indices.