epygram.geometries.AbstractGeometry
— Geometry class¶
Contains the classes for 3D geometries of fields.
- class epygram.geometries.AbstractGeometry.Geometry(grid, dimensions, vcoordinate, position_on_horizontal_grid='__unknown__', geoid=None)[source]¶
Bases:
epygram.util.RecursiveObject
Handles the geometry for a 3-Dimensions Field. Abstract mother class.
- Parameters
grid – Handles description of the horizontal grid.
dimensions – Handles grid dimensions.
vcoordinate – Handles vertical geometry parameters.
position_on_horizontal_grid –
Position of points w/r to the horizontal. among: [‘upper-right’, ‘upper-left’,
’lower-left’, ‘lower-right’, ‘center-left’, ‘center-right’, ‘lower-center’, ‘upper-center’, ‘center’, ‘__unknown__’]
geoid – To specify geoid shape.
- azimuth(*args, **kwargs)¶
Initial bearing from end1 to end2 points following a Great Circle.
- Parameters
end1 – must be a tuple (lon, lat) in degrees.
end2 – must be a tuple (lon, lat) in degrees.
Warning: requires the
pyproj
module.
- cartoplot_geometry(**kwargs)[source]¶
Makes a simple plot of the geometry, using cartopy. For kwargs please refer to epygram.geometries.domain_making.output.cartoplot_rect_geometry
- cartopy_CRS_reproject(lons, lats, projection=None)¶
Note
Requires plugin: with_cartopy (config.activate_plugins)
Reproject lons/lats onto a cartopy CRS projection coordinates.
- property datashape¶
Returns the data shape requested by this geometry.
- distance(*args, **kwargs)¶
Computes the distance between two points along a Great Circle.
- Parameters
end1 – first point, must be a tuple (lon, lat) in degrees.
end2 – second point, must be a tuple (lon, lat) in degrees.
If one of (end1, end2) is a tuple of arrays (like (<array of lon>, <array of lat>)) the other one must be a scalar tuple or a tuple of arrays with same dimensions.
Warning: requires the
pyproj
module.
- eq_Hgeom(other)[source]¶
Tests if the horizontal part of the geometry is equal to the horizontal part of another geometry. :param: other: other geometry to use in the comparison
- get_levels(d4=False, nb_validities=0, subzone=None)[source]¶
Returns an array containing the level for each data point.
- Parameters
d4 –
if True, returned values are shaped in a 4 dimensions array
if False, shape of returned values is determined with respect to geometry d4=True requires nb_validities > 0
nb_validities – the number of validities represented in data values
subzone – optional, among (‘C’, ‘CI’), for LAM grids only, extracts the levels resp. from the C or C+I zone off the C+I(+E) zone.
Levels are internally stored with the vertical dimension first whereas this method puts the time in first dimension.
- linspace(*args, **kwargs)¶
Returns evenly spaced points over the specified interval. Points are lined up along a Great Circle.
- Parameters
end1 – must be a tuple (lon, lat) in degrees.
end2 – must be a tuple (lon, lat) in degrees.
num – the number of points, including point1 and point2.
Warning: requires the
pyproj
module.
- make_physicallevels_geometry()[source]¶
Returns a new geometry excluding levels with no physical meaning.
- Parameters
getdata – if False returns a field without data
- make_section_geometry(end1, end2, points_number=None, resolution=None, position=None)[source]¶
Returns a Geometry.
- Parameters
end1 – must be a tuple (lon, lat) in degrees.
end2 – must be a tuple (lon, lat) in degrees.
points_number – defines the total number of horizontal points of the section (including ends). If None, defaults to a number computed from the ends and the resolution.
resolution – defines the horizontal resolution to be given to the field. If None, defaults to the horizontal resolution of the field.
position – defines the position of data in the grid (for projected grids only)
- make_vtkGrid(*args, **kwargs)¶
Note
Requires plugin: with_vtk (config.activate_plugins)
Makes an empty grid to use with vtk
- Parameters
rendering – a usevtk.Usevtk instance
subzone –
optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.
Default is no subzone, i.e. the whole field.
- make_zoom_geometry(zoom, extra_10th=False)[source]¶
Returns an unstructured geometry with the points contained in zoom.
- Parameters
zoom – a dict(lonmin=, lonmax=, latmin=, latmax=).
extra_10th – if True, add 1/10th of the X/Y extension of the zoom (only usefull for the regular_lonlat grid implementation).
- plot3DBluemarble(rendering, subzone=None, interpolation='nearest', color_transform=None)¶
Note
Requires plugin: with_vtk (config.activate_plugins)
This method adds the NOAA’s bluemarble image to the vtk rendering system. The image is projected on the vertical coordinate of this geometry.
- Parameters
rendering – a usevtk.Usevtk instance
subzone –
optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.
Default is no subzone, i.e. the whole field.
interpolation – interpolation method to use to compute levels at each pixel
color_transform –
- if not None, must be a user-defined function with parameters
(rgb, alpha, (lons, lats)) with rgb an array representing the rgb values on each of the image points, alpha the alpha values on the same points and (lons, lats) a turple of the points coordinate. The function must return (rgb, alpha). This enables the color modification of the image. For example, the following function transforms the color into grey levels:
- def grey(rgb, alpha, ll):
rgb[:, :, :] = rgb.mean(axis=2)[:, :, numpy.newaxis] return rgb, alpha
- plot3DMaptiles(rendering, url, resol_factor, minzoom=1, maxzoom=18, subzone=None, interpolation='nearest', color_transform=None)¶
Note
Requires plugin: with_vtk (config.activate_plugins)
This method adds tiles image to the vtk rendering system. The image is projected on the vertical coordinate of this geometry.
- Parameters
rendering – a usevtk.Usevtk instance
url – url to get the map tiles to use ex: https://a.tile.openstreetmap.org/${z}/${x}/${y}.png where ${z}, ${x} and ${y} are place holders for zoom, x and y position of the tile
resol_factor – how many times the tile resolution must be approximately better than the geometry resolution. A factor of 2 (resp. 1/2.) induce using the next (resp. preceding) zoom level.
minzoom/maxzoom – minimum and maximum zoom levels to use
subzone –
optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.
Default is no subzone, i.e. the whole field.
interpolation – interpolation method to use to compute levels at each pixel
color_transform –
- if not None, must be a user-defined function with parameters
(rgb, alpha, (lons, lats)) with rgb an array representing the rgb values on each of the image points, alpha the alpha values on the same points and (lons, lats) a turple of the points coordinate. The function must return (rgb, alpha). This enables the color modification of the image. For example, the following function transforms the color into grey levels:
- def grey(rgb, alpha, ll):
rgb[:, :, :] = rgb.mean(axis=2)[:, :, numpy.newaxis] return rgb, alpha
Zoom computation is done supposing that each tile is made of 256 * 256 pixels.
URL examples (these URLs have been found on internet but some are protected with copyrights and must not be used with this tool or kept in cache; please check before use):
- osm: a (full?) list can be found on https://wiki.openstreetmap.org/wiki/Tile_servers
or https://wiki.openstreetmap.org/wiki/Tiles The most common one is certainly: https://a.tile.openstreetmap.org/${z}/${x}/${y}.png
google maps: it seems to be forbidden to use this tiles outside of google products.
- plot3DProjImage(rendering, filename, geometry, subzone=None, interpolation='nearest', color_transform=None)¶
Note
Requires plugin: with_vtk (config.activate_plugins)
This method adds an image to the vtk rendering system. The image is projected on the vertical coordinate of this geometry.
- Parameters
rendering – a usevtk.Usevtk instance
filename – path to an image file
geometry – projection associated to the geometry
subzone –
optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.
Default is no subzone, i.e. the whole field.
interpolation – interpolation method to use to compute levels at each pixel
color_transform –
- if not None, must be a user-defined function with parameters
(rgb, alpha, (lons, lats)) with rgb an array representing the rgb values on each of the image points, alpha the alpha values on the same points and (lons, lats) a turple of the points coordinate. The function must return (rgb, alpha). This enables the color modification of the image. For example, the following function transforms the color into grey levels:
- def grey(rgb, alpha, ll):
rgb[:, :, :] = rgb.mean(axis=2)[:, :, numpy.newaxis] return rgb, alpha
first_corner and last_corner describe the coverage of the image from the left edge of the leftmost pixel to the right edge of the rightmost pixel.
- plotgeometry(plotlib='cartopy', **kwargs)[source]¶
Makes a simple plot of the geometry, with a number of options.
- Parameters
plotlib – library to be used for plotting: ‘basemap’ is DEPRECATED; ‘cartopy’ (default) is recommended !
- property projected_geometry¶
Is the geometry a projection ?
- property rectangular_grid¶
Is the grid rectangular ?
- property structure¶
Returns the structure of the grid which depends on the prsent dimensions
- vcoord_as_field(surface_type, validity=None, levels=None)[source]¶
Returns a field filled with the level values associated to a fake geometry :param validity: validities to associate with the returned field
if None, we try without setting validity
- Parameters
surface_type – typeOfFirstFixedSurface to associate to the fake geometry
levels – list of values to use as the levels of the fake geometry if None, levels will be replaced by a range
- what(out=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, vertical_geometry=True, arpifs_var_names=False, spectral_geometry=None)[source]¶
Writes in file a summary of the geometry.
- Parameters
out – the output open file-like object (duck-typing: out.write() only is needed).
vertical_geometry – if True, writes the vertical geometry of the field.
arpifs_var_names – if True, prints the equivalent ‘arpifs’ variable names.
spectral_geometry – an optional dict containing the spectral truncatures {‘in_X’:, ‘in_Y’:} (LAM) or {‘max’:} (global).
- class epygram.geometries.AbstractGeometry.RectangularGridGeometry(grid, dimensions, vcoordinate, position_on_horizontal_grid='__unknown__', geoid=None)[source]¶
Bases:
epygram.geometries.AbstractGeometry.Geometry
Handles the geometry for a rectangular 3-Dimensions Field. Abstract.
- Parameters
grid – Handles description of the horizontal grid.
dimensions – Handles grid dimensions.
vcoordinate – Handles vertical geometry parameters.
position_on_horizontal_grid –
Position of points w/r to the horizontal. among: [‘upper-right’, ‘upper-left’,
’lower-left’, ‘lower-right’, ‘center-left’, ‘center-right’, ‘lower-center’, ‘upper-center’, ‘center’, ‘__unknown__’]
geoid – To specify geoid shape.
- default_cartopy_CRS()¶
Note
Requires plugin: with_cartopy (config.activate_plugins)
Create a cartopy.crs appropriate to the Geometry.
By default, a PlateCarree (if the domain gets close to a pole) or a Miller projection is returned.
- extract_subzone(data, subzone)[source]¶
Extracts the subzone C or CI from a LAM field.
- Parameters
data – the data values with shape concording with geometry.
subzone – optional, among (‘C’, ‘CI’), for LAM grids only, extracts the data resp. from the C or C+I zone off the C+I(+E) zone.
- fill_maskedvalues(data, fill_value=None)[source]¶
Returns a copy of data with masked values filled with fill_value.
- get_datashape(dimT=1, force_dimZ=None, d4=False, subzone=None)[source]¶
Returns the data shape according to the geometry.
- Parameters
force_dimZ – if supplied, force the Z dimension instead of that of the vertical geometry
dimT – if supplied, is the time dimension to be added to the data shape
d4 –
if True, shape is 4D
if False, shape has only those > 1
subzone – optional, among (‘C’, ‘CI’), for LAM grids only, informes that data is resp. on the C or C+I zone off the C+I(+E) zone.
- get_lonlat_grid(subzone=None, position=None, d4=False, nb_validities=0, force_longitudes=None)[source]¶
Returns a tuple of two tables containing one the longitude of each point, the other the latitude, with 2D shape.
- Parameters
subzone –
optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.
Default is no subzone, i.e. the whole field.
position – position of lonlat grid with respect to the model cell. Defaults to self.position_on_horizontal_grid.
d4 –
if True, returned values are shaped in a 4 dimensions array
if False, shape of returned values is determined with respect to geometry. d4=True requires nb_validities > 0
nb_validities – number of validities represented in data values
force_longitudes – if ‘positive’, the longitudes will be forced positive if ‘]-180,180]’, the longitudes will be in the ]-180, 180] interval
Shape of 2D data on Rectangular grids:
grid[0,0] is SW, grid[-1,-1] is NE
grid[0,-1] is SE, grid[-1,0] is NW
- gimme_corners_ij(subzone=None)[source]¶
Returns the indices (i, j) of the four corners of a rectangular grid, as a dict(corner=(i, j)) with corner in:
ll = lower-left / lr = lower-right / ur = upper-right / ul = upper-left.
(0, 0) is always the lower-left corner of the grid.
- Parameters
subzone – for LAM fields, returns the corners of the subzone.
- gimme_corners_ll(subzone=None, position=None)[source]¶
Returns the lon/lat of the four corners of a rectangular grid, as a dict(corner=(lon, lat)) with corner in:
ll = lower-left / lr = lower-right / ur = upper-right / ul = upper-left.
- Parameters
subzone – for LAM grids, returns the corners of the subzone.
position – position of corners with respect to the model cell. Defaults to self.position_on_horizontal_grid.
- property gridpoints_number¶
Returns the number of gridpoints of the grid.
- Parameters
subzone –
optional, among (‘C’, ‘CI’), for LAM grids only, returns the grid resp. for the C or C+I zone off the C+I+E zone.
Default is no subzone, i.e. the whole field.
- horizontally_flattened(data)[source]¶
Returns a copy of data with horizontal dimensions flattened. data must be 4D for simplicity reasons.
- property isglobal¶
- Returns
True if geometry is global
- make_subarray_geometry(first_i, last_i, first_j, last_j)[source]¶
Make a modified geometry consisting in a subarray of the grid, defined by the indexes given as argument.
- make_subsample_geometry(sample_x, sample_y, sample_z)[source]¶
Make a sample geometry by decreasing resolution. :param sample_x: take one over <sample_x> points in the x direction :param sample_y: same for the y direction :param sample_z: same for the z direction
CAUTION: if your grid contains non physical point, these points can be retain in subsample. Use select_zone beforehand to suppress these points.
- nearest_points(lon, lat, request, position=None, external_distance=None, squeeze=True)[source]¶
Returns the (i, j) positions of the nearest points.
- Parameters
lon – longitude of point in degrees.
lat – latitude of point in degrees.
request –
criteria for selecting the points, among: * {‘n’:’1’} - the nearest point * {‘n’:’2*2’} - the 2*2 square points around the position * {‘n’:’4*4’} - the 4*4 square points around the position * {‘n’:’N*N’} - the N*N square points around the position: N must be even * {‘radius’:xxxx, ‘shape’:’square’} - the points which are xxxx metres
around the position in X or Y direction
{‘radius’:xxxx, ‘shape’:’circle’} - the points within xxxx metres around the position. (default shape == circle)
position – position in the model cell of the lat lon position. Defaults to self.position_on_horizontal_grid.
external_distance – can be a dict containing the target point value and an external field on the same grid as self, to which the distance is computed within the 4 horizontally nearest points; e.g. {‘target_value’:4810, ‘external_field’:a_3DField_with_same_geometry}. If so, the nearest point is selected with distance = |target_value - external_field.data| Only valid with request={‘n’:’1’}
squeeze – True to suppress useless dimensions
- Return type
general output form is [list, list, …, list] with as many list items as the length of lon/lat. Each list item is of the form [tuple, tuple, …, tuple] with as many tuples as the request implies. A tuple represents one of the nearest points associated with one value taken from lon/lat. Each tuple as the form (i, j).
Dimensions with a length of one are removed except if squeeze is False. If squeeze is True and if request implies only one nearest point, the list item of the general output form is replaced by the tuple item; if length of lon/lat is one, the output is directly the list item of the general output form. Hence, if length of lon/lat is one and the request implies only one point, the output is a tuple.
In case of a simple square request, output is actually an array. Otherwise, the output is as described (it cannot be an array because the number of nearest points can vary with the entry point).
In case of a {‘n’:’2*2’} request, order of points obtained on a rectangular grid is (and must be) such that first and second point share the i position (hence third and forth point also share the i position) and first and third share the j position (hence the second and forth also share the j position).
- point_is_inside_domain_ij(i=None, j=None, margin=- 0.1, subzone=None)[source]¶
Returns True if the point(s) of i/j coordinates is(are) inside the field.
- Parameters
i – X index of point
j – Y index of point.
margin – considers the point inside if at least ‘margin’ points far from the border. The -0.1 default is a safety for precision errors.
subzone – considers only a subzone among (‘C’, ‘CI’) of the domain.
- point_is_inside_domain_ll(lon, lat, margin=- 0.1, subzone=None, position=None)[source]¶
Returns True if the point(s) of lon/lat coordinates is(are) inside the field.
- Parameters
lon – longitude of point(s) in degrees.
lat – latitude of point(s) in degrees.
margin – considers the point inside if at least ‘margin’ points far from the border. The -0.1 default is a safety for precision errors.
subzone – considers only a subzone among (‘C’, ‘CI’) of the domain.
position – position of the grid with respect to the model cell. Defaults to self.position_on_horizontal_grid.
- reshape_data(data, first_dimension=None, d4=False, subzone=None)[source]¶
Returns a 2D data (horizontal dimensions) reshaped from 1D, according to geometry.
- Parameters
data – the 1D data (or 3D with a T and Z dimensions, or 2D with either a T/Z dimension, to be specified), of dimension concording with geometry. In case data is 3D, T must be first dimension and Z the second.
first_dimension – in case data is 2D, specify what is the first dimension of data among (‘T’, ‘Z’)
subzone – optional, among (‘C’, ‘CI’), for LAM grids only, informes that data is resp. on the C or C+I zone off the C+I(+E) zone.
d4 –
if True, returned values are shaped in a 4 dimensions array
if False, shape of returned values is determined with respect to geometry