Reference Guide 

This manual details, for each module of lightvegemanager, the functions and objects included in lightvegemanager, describing what they are and what they do.

`LVM` module

LightVegeManager 

Main class of the tool. Calls all the other modules in src.

3 inputs dict for setting all parameters:

geometry = {
            "scenes" : [scene0, scene1, scene2, ...] ,
            "domain" : ((xmin, ymin), (xmax, ymax)),
            "stems id" : [(id_element, id_scene), ...],
            "transformations" : {
                                    "scenes unit" : kwarg ,
                                    "rescale" : kwarg ,
                                    "translate" : kwarg ,
                                    "xyz orientation" : kwarg
                                    }
                }

environment = {
                "coordinates" : [latitude, longitude, timezone] ,

                "sky" : "turtle46" ,
                "sky" : ["file", filepath] ,
                "sky" : [nb_azimut, nb_zenith, "soc" or "uoc"] ,

                "direct" : bool, # sun radiations
                "diffus" : bool, # sky radiations
                "reflected" : bool, # reflected radiation in the canopy
                "infinite" : bool, # infinitisation of the scene
                }

Currently LightVegeManager handles the light models RATP and CARIBU:

caribu_args = {
                "sun algo" : "ratp",
                "sun algo" : "caribu",

                    "caribu opt" : {
                                    band0 = (reflectance, transmittance),
                                    band1 = (reflectance, transmittance),
                                    ...
                                    },
                    "debug" : bool,
                    "soil mesh" : bool,
                    "sensors" : ["grid", dxyz, nxyz, orig]
                }

ratp_args = {
                # Grid specifications
                "voxel size" : [dx, dy, dz],
                "voxel size" : "dynamic",

                "origin" : [xorigin, yorigin, zorigin],
                "origin" : [xorigin, yorigin],

                "number voxels" : [nx, ny, nz],
                "grid slicing" : "ground = 0."
                "tesselation level" : int

                # Leaf angle distribution
                "angle distrib algo" : "compute global",
                "angle distrib algo" : "compute voxel",
                "angle distrib algo" : "file",

                "nb angle classes" : int,
                "angle distrib file" : filepath,

                # Vegetation type
                "soil reflectance" : [reflectance_band0, reflectance_band1, ...],
                "reflectance coefficients" : [reflectance_band0, reflectance_band1, ...],
                "mu" : [mu_scene0, mu_scene1, ...]
            }

See also

For more details Inputs description

class LVM.LightVegeManager(environment={}, lightmodel='', lightmodel_parameters={}, main_unit='m')[source]

Bases: object

Main class for the tool LightVegeManager

Common simulation order:

input geometries -> build and prepare data -> call light model -> transfer results to plant models

It includes:

Main methods:

__init__: initializes and builds static object for the rest of simulation

build(): builds and prepare all geometric meshes

run(): calls a light model and manages its inputs and outputs

Transfer methods:

to_MTG(): transfers ligthing results to a MTG table

to_l_egume(): transfers ligthing results to l-egume by creating two arrays as inputs for the plant model

Analysis tools: analyses a set of triangles and formats them as a turbid medium inputs

s5(): fortran tool

s2v(): c++ tool

Visualisation tools:

plantGL_nolight(): return a plantGL scene from the geometry

plantGL_light(): return a plantGL scene from the geometry with lighting results

plantGL_sensors(): return a plantGL scene from virtual sensors if created

VTK_nolight(): write VTK file with only geometric informations

VTK_light(): write VTK file with geometric informations and associated light results

VTK_sun(): write VTK file representing the sun as a line

Getters: to use light results with external routines

riri5_transmitted_light()

riri5_intercepted_light()

elements_outputs()

triangles_outputs()

voxels_outputs()

sensors_outputs()

sun()

soilenergy()

maxtrianglearea()

legume_empty_layers()

tesselationtime()

modelruntime()

leafangledistribution()

Parameters:

environment (dict, optional) – Environment parameters, defaults to {}
lightmodel (str, optional) – either "ratp" or "caribu", defaults to “”
lightmodel_parameters (dict, optional) – light model parameters, defaults to {}
main_unit (str, optional) – measure unit for the global scene where the light will be computed, defaults to “m”

Raises:

ValueError – lightmodel entry not valid, either 'ratp' or 'caribu'

build(geometry={}, global_scene_tesselate_level=0)[source]

Builds a mesh of the simulation scene in the right light model format

Parameters:

geometry (dict, optional) – geometric parameters, contains geometric scenes, defaults to {}
global_scene_tesselate_level (int, optional) – option to subdivide all triangles of the mesh a certain number of times (to fine tuning the mesh), defaults to 0

Raises:

ValueError – Currently, converting voxels mesh to triangles mesh is not possible

run(energy=0.0, day=0, hour=0, parunit='micromol.m-2.s-1', truesolartime=False, id_sensors=None)[source]

Calls the light model and formats lighting results

Parameters:

energy (float, optional) – input radiation energy, defaults to 0
day (int, optional) – simulation day, defaults to 0
hour (int, optional) – simulation hour, defaults to 0
parunit (str, optional) – input energy unit, light models manages radiations in different unit, you can precise input unit and LightVegeManager will convert it in the right unit, defaults to “micromol.m-2.s-1”
truesolartime (bool, optional) – simulation hour is a true solar time or local time (depending on simulation coordinates), defaults to False
id_sensors (list, optional) – if you use CARIBU with a grid of virtual sensors, you have to precise which input scenes the grid must match, defaults to None

Raises:

ValueError – with CARIBU you can precise the sun algorithm to calculate sun position, can be either "caribu" or "ratp"
ValueError – valid radiations are "direct", "diffuse", "reflected"

to_MTG(energy=1.0, mtg=None, id=None)[source]

Transfers lighting results to a MTG table.

Warning

The run() must have been called before to have results dataframes.

Results are pandas.Dataframe stored in the self

Parameters:

energy (float, optional) – input energy, defaults to 1
mtg (MTG, optional) – MTG table with "PARa" and "Erel" entries in its properties, defaults to None
id (list or tuple, optional) – you can precise to which input scenes the MTG table corresponds, defaults to None

Raises:

AttributeError – you need to call :func:run first

to_l_egume(energy=1.0, m_lais=[], list_lstring=[], list_dicFeuilBilanR=[], list_invar=[], id=None)[source]

Transfers lighting results to l-egume

Warning

The run() must have been called before to have results dataframes.

Warning

l-egume needs transmitted energy informations located in a grid of voxels. You need to have the same dimensions in the lighting results.

With RATP, RATP grid must have the same dimensions as l-egume intern grid.
With CARIBU, you must create a grid of virtual sensors in the same dimensions as l-egume intern grid.

Results are pandas.Dataframe stored in the self

Parameters:

energy (float, optional) – input energy, defaults to 1
m_lais (numpy.array, optional) – leaf area represented in a numpy.array of dimension [number of species, number of z layers, number of y layers, number of x layers], defaults to []
list_lstring (list of dict, optional) – from l-egume, each element corresponds to an input specy of l-egume. Each element is a dict lstring stores the l-system of each plant, defaults to []
list_dicFeuilBilanR (list of dict, optional) – from l-egume, each element corresponds to an input specy of l-egume. Each element is a dict dicFeuiBilanR stores correspondances between voxels grid and each plant, defaults to []
list_invar (list of dict, optional) – from l-egume, each element corresponds to an input specy of l-egume. Each element is a dict invar stores instant intern variables of l-egume., defaults to []
id (list, optional) – list of indices from input scenes which corresponds to current l-egume instance. If you have several plantmodel among the input scenes, you need to precise which results you want to transfer to which instance of l-egume. defaults to None

Raises:

AttributeError – you need to call run() first
ValueError – unknown light model

Returns:

if light model is RATP transfer_ratp_legume() :

res_abs_i: absorbed energy in each voxels of a grid matching the dimensions of l-egume intern grid of voxels. One value for each specy.

res_trans: transmitted energy in each voxels of a grid matching the dimensions of l-egume intern grid of voxels

if light model is CARIBU :func:transfer_caribu_legume :

update of list_invar: updates the keys "parap" and "parip" for each specy. Cumulatative energy per plant

res_trans: transmitted energy in each voxels of a grid matching the dimensions of l-egume intern grid of voxels

Return type:

numpy.array

s5()[source]

Creates inputs files for s5 and runs it s5 is an external tool made to analyse a set of triangles in order to use a grid of voxels. It also computes leaf angle distribution from the triangulation

Note

All files are located in s5 folder

Input files created

fort.51: contains triangulation. Possibility to precise stem elements it is registered in the instance of LightVegeManager

s5.par: stores grid of voxels informations and number of entities

Output files created

fort.60

dimensions xy of the grid

stats by specy

total leaf area

leaf area index

global zenital leaf angle distribution

global azimutal leaf angle distribution

stats by voxels

#specy | #ix | #iy | #iz (coordinate xyz of the voxel) | eaf area density

local zenital leaf angle distribution

local azimutal leaf angle distribution

leafarea: for each specy, for each voxel

ix | iy | iz | #specy | LAD | zenital-distribution | azimutal-distribution

example

>>> myscene # a plantgl Scene
>>> testofs5 = LightVegeManager() # create a instance
>>> testofs5.build( geometry={ "scenes" : [myscene] } ) # build the geometry
>>> testofs5.s5() # run of s5, creates input and output files

s2v()[source]

Creates inputs files for s2v and runs it s5 is an external tool made to analyse a set of triangles in order to use a grid of voxels. It also computes leaf angle distribution from the triangulation

Note

All files are located in s2v folder

Input files created

fort.51: stores triangulation. Possibility to precise stem elements it is registered in the instance of LightVegeManager

s2v.par: stores grid of voxels informations and number of entities

Output files created

s2v.log

logs about processing

global statistics

total leaf area per specy

total leaf area

leaf area index

global zenital leaf angle distribution

s2v.can

z layer where each triangle is located (and copy its vertices)

s2v.area

triangle id | z layer | triangle area

out.dang: SAIL file

line 1: global leaf area index for specy 1 line 2: global zenital leaf angle distribution for specy 1

leafarea: SAIL file

each line: 0 | idz | leaf area index for each slope class in current z layer | 0 | 0 | leaf area density on the layer

example

>>> myscene # a plantgl Scene
>>> testofs2v = LightVegeManager() # create a instance
>>> testofs2v.build( geometry={ "scenes" : [myscene] } ) # build the geometry
>>> testofs2v.s2v() # run of s2v, creates input and output files

to_VTK(lighting=False, path='', i=0, printtriangles=True, printvoxels=True, virtual_sensors=False, sun=False, sun_scale=2, sun_origin=(0, 0, 0), sun_center=True)[source]

Writes a VTK from mesh(es) in self

Warning

If lighting=True, the run() must have been called before to have results dataframes.

Note

if sun_center is False, sun_origin is the starting point of the line and it ends at sun_origin + sun_scale*sun.position, if sun_center is True, sun_origin is the middle point of the line.

Parameters:

lighting (bool, optional) – for writing lighting information associated with each element, defaults to False
path (string, optional) – file and path names for the VTK file(s)
i (int, optional) – time iteration of the current VTk file(s)
printtriangles (bool, optional) – write triangulation if one has been created in :func:build, defaults to True
printvoxels (bool, optional) – write grid of voxels if one has been created in :func:build, defaults to True
virtual_sensors (bool, optional) – write grid of virtual sensors if one has been created in :func:build, defaults to False
sun (bool, optional) – write a line representing the sun position, defaults to False
sun_scale (int, optional) – size of the line, defaults to 2
sun_origin (tuple, optional) – starting or middle point of the line, defaults to (0,0,0)
sun_center (bool, optional) – if True orig is the middle of the line, otherwise it is the starting point, defaults to True

Raises:

AttributeError – it needs to have lighting informations
AttributeError – it needs to have a grid of virtual sensors

to_plantGL(lighting=False, printtriangles=True, printvoxels=False, virtual_sensors=False)[source]

Return a plantGL Scene from mesh(es) in self

Warning

If lighting=True, the run() must have been called before to have results dataframes.

Parameters:

lighting (bool, optional) – for writing lighting information associated with each element, defaults to False
printtriangles (bool, optional) – write triangulation if one has been created in build(), defaults to True
printvoxels (bool, optional) – write grid of voxels if one has been created in build(), defaults to False
virtual_sensors (bool, optional) – write grid of virtual sensors if one has been created in :func:build, defaults to False

Raises:

AttributeError – AttributeError

Returns:

Returns plantGL Scene with triangles and/or voxels from the final mesh

Return type:

plantgl.Scene

Returns:

Returns plantGL Scene with a grid of virtual sensors

Return type:

plantgl.Scene

property riri5_transmitted_light

transmitted results if light model is RiRi light

Returns:: transmitted energy following a grid of voxels
Return type:: numpy.array

property riri5_intercepted_light

Intercepted results if light model is RiRi light,

Returns:: intercepted energy following a grid of voxels, for each specy
Return type:: numpy.array

property elements_outputs

Lighting results aggregate by element

Returns:: Column names can change depending on the light model. Commonly, there is element indice, its area and intercepted energy
Return type:: pandas.Dataframe

property triangles_outputs

Lighting results aggregate by triangle, if it has a triangulation in its inputs

Returns:

See also

outputs for column names

Return type:

pandas.Dataframe

property voxels_outputs

Lighting results aggregate by voxels, only with RATP as the selected light model

Returns:

See also

outputs for column names

Return type:

pandas.Dataframe

sensors_outputs(dataframe=False)[source]

Lighting results aggregate by sensors. Only with CARIBU if you activated the virtual sensors option

Returns:: The output format is the same as CARIBU output format. Dict with Eabs key for absorbed energy and Ei for incoming energy
Return type:: dict

property sun

Return sun position of the last :func:run call

Returns:: vector (x, y, z)
Return type:: tuple

property soilenergy

Return soil energy, only with CARIBU if soilmesh option is activated

Returns:: The output format is the same as CARIBU output format. Dict with Eabs key for absorbed energy and Ei for incoming energy
Return type:: dict

property maxtrianglearea

Returns the largest triangle of triangles mesh Computed in build()

Returns:: area the triangle
Return type:: float

property legume_empty_layers

Returns number of empty layers between top of the canopy and number of z layers expected by l-egume

Returns:: result of fill_ratpgrid_from_legumescene()
Return type:: int

property tesselationtime

_summary_

Returns:: _description_
Return type:: _type_

property modelruntime

Returns running time of the light model

Returns:: time in s
Return type:: float

property leafangledistribution

property domain

Returns the largest triangle of triangles mesh Computed in build()

Returns:: area the triangle
Return type:: float

`CARIBUinputs` module

CARIBUinputs 

Manages and prepares input information for CARIBU.

In this module we use two of the LightVegeManager’s inputs dict.

parameters corresponding to CARIBU parameters and contains

caribu_args = {
                "sun algo" : "ratp",
                "sun algo" : "caribu",

                "caribu opt" : {
                                band0 = (reflectance, transmittance),
                                band1 = (reflectance, transmittance),
                                ...
                                },
                "debug" : bool,
                "soil mesh" : bool,
                "sensors" : ["grid", dxyz, nxyz, orig]
                }

geometry corresponding to the geometric information with the scenes inputs

geometry = {
            "scenes" : [scene0, scene1, scene2, ...] ,
            "domain" : ((xmin, ymin), (xmax, ymax)),
            "stems id" : [(id_element, id_scene), ...],
            "transformations" : {
                                    "scenes unit" : kwarg ,
                                    "rescale" : kwarg ,
                                    "translate" : kwarg ,
                                    "xyz orientation" : kwarg
                                }
            }

See also

For more details Inputs description

CARIBUinputs.Prepare_CARIBU(trimesh, geometry, matching_ids, minmax, parameters, infinite, idsensors)[source]

Format optical parameters and prepare virtual sensors and debug if activated

Parameters:

trimesh (dict) –
triangles mesh aggregated by indice elements
```
{ id : [triangle1, triangle2, ...]}
```
geometry (dict) – geometric parameters from inputs of LightVegeManager
matching_ids (dict) –
dict that matches new element indices in trimesh with specy indice and input element indice,
```
matching_ids = { new_element_id : (input_element_id, specy_id)}
```
minmax ([3-tuple, 3-tuple]) – list of mininuml point and maximum point in a triangles mesh
parameters (dict) – RATP parameters from inputs of LightVegeManager
infinite (bool) – if the user wishes to activate infinitisation of the grid
idsensors (list of int) – Sets which input scenes the grid of virtual sensors will match. Elements of this list refers to indices in the list geometry["scenes"]. If no input indices are given, the grid will match the global scene trimesh. Otherwise, you can match the grid to a specific set of input scenes

Returns:

opt: optical parameters formatted for CARIBU. It takes the form of dict, where each
key is a bandlength (PAR, NIR etc…) and values are transmittance and reflectance (or only reflectance for stems elements)
sensors_caribu: geometric data of the virtual sensors in CARIBU scene format. Sensors
are horizontal square made of two triangles
sensors_caribu = { sensor_id : [triangle1, triangle2], ...}
debug: boolean if user wants to activate th edebug option in CARIBU
matching_sensors_species: dict where each key is a sensor ID and value, its matching input vegetation type

Return type:

dict, dict, bool, dict

CARIBUinputs.CARIBU_opticals(matching_ids, parameters, stems_id=None)[source]

Sets optical parameters for CARIBU from LightVegeManager inputs It removes transmittance for stems elements if precised

Parameters:

matching_ids (dict) – dict that matches new element indices in trimesh with specy indice and input element indice, matching_ids = { new_element_id : (input_element_id, specy_id)}
parameters (dict) – RATP parameters from inputs of LightVegeManager
stems_id (list of 2-tuple, optional) – list of potential stems element in the input scenes, defaults to None

Returns:

optical parameters formatted for CARIBU. It takes the form of dict, where each key is a bandlength (PAR, NIR etc…) and values are transmittance and reflectance (or only reflectance for stems elements)

Return type:

dict

CARIBUinputs.create_caribu_legume_sensors(dxyz, nxyz, orig, pmax, trimesh, matching_ids, id_sensors, infinite, start_id=0)[source]

Creates a set of virtual sensors following a voxels grid each sensor is a square made by two triangles and takes place on the bottom face of a voxel The grid follow the xyz axis (and so the voxels)

Parameters:

dxyz (list) – [dx, dy, dz] size of a voxel in each direction
nxyz (list) – [nx, ny, nz] number of voxels on each axis
orig (list (or tuple)) – [x_origin, y_origin, z_origin], origin of the grid, cartesian coordinates
pmax (lsit (or tuple)) – [x, y, z] maximum point of trimesh in the xyz space
trimesh (dict) –
triangles mesh aggregated by indice elements
```
{ id : [triangle1, triangle2, ...]}
```
matching_ids (dict) – dict that matches new element indices in trimesh with specy indice and input element indice, matching_ids = { new_element_id : (input_element_id, specy_id)}
idsensors (list of int) – Sets which input scenes the grid of virtual sensors will match. Elements of this list refers to indices in the list geometry["scenes"]. If no input indices are given, the grid will match the global scene trimesh. Otherwise, you can match the grid to a specific set of input scenes
infinite (bool) – if the user wishes to activate infinitisation of the grid

Returns:

it returns 3 objects:

sensors_caribu, geometric data of the virtual sensors in CARIBU scene format. Sensors
are horizontal square made of two triangles sensors_caribu = { sensor_id : [triangle1, triangle2], ...}

s_capt, PlantGL scene of the virtual sensors

sensors_maxcenter, [x, y, z] representing point on the highest sensors layer and middle of
xy plane in the grid

Return type:

dict, PlantGL scene, list

CARIBUinputs.run_caribu(c_scene, direct_active, infinite, sensors, energy=1.0)[source]

runs caribu depending on input options

Parameters:

c_scene (CaribuScene) – instance of CaribuScene containing geometry, light source(s), opt etc…
direct_active (bool) – Whether only first order interception is to be computed, default is True (no rediffusions)
infinite (bool) – if the user wishes to activate infinitisation of the grid
sensors (dict) –
geometric data of the virtual sensors in CARIBU scene format. Sensors are horizontal square made of two triangles
```
sensors_caribu = { sensor_id : [triangle1, triangle2], ...}
```
energy (float, optional default is 1.) – input energy value

Returns:

results are stored in two dict

raw (dict of dict) a {band_name: {result_name: property}} dict of dict.
Except for result_name=’sensors’, each property is a {primitive_id: [values,]} dict containing results for individual triangles of the primitive
aggregated (dict of dict)a {band_name: {result_name: property}}
Except for result_name=’sensors’, each property is a {primitive_id: value} dict containing aggregated results for each primitive

result_name are :

area (float): the individual areas (m2)

Eabs (float): the surfacic density of energy absorbed (m-2)

Ei (float): the surfacic density of energy incoming (m-2) additionally, if split_face is True

Ei_inf (float): the surfacic density of energy incoming on the inferior face (m-2)

Ei_sup (float): the surfacic density of energy incoming on the superior face (m-2)

sensors (dict of dict): area, surfacic density of incoming direct energy and surfacic density of incoming total energy of sensors grouped by id, if any

Return type:

dict of dict, dict of dict

`RATPinputs` module

RATPinputs 

Manage vegetation and meteo input informations for RATP

The argument parameters refers to one the three inputs dict of LightVegeManager. It is structured as so:

ratp_args = {
        # Grid specifications
        "voxel size" : [dx, dy, dz],
        "voxel size" : "dynamic",

        "origin" : [xorigin, yorigin, zorigin],
        "origin" : [xorigin, yorigin],

        "number voxels" : [nx, ny, nz],
        "grid slicing" : "ground = 0.",
        "tesselation level" : int,

        "full grid" : bool,

        # Leaf angle distribution
        "angle distrib algo" : "compute global",
        "angle distrib algo" : "compute voxel",
        "angle distrib algo" : "file",

        "nb angle classes" : int,
        "angle distrib file" : filepath,

        # Vegetation type
        "soil reflectance" : [reflectance_band0, reflectance_band1, ...],
        "reflectance coefficients" : [reflectance_band0, reflectance_band1, ...],
        "mu" : [mu_scene0, mu_scene1, ...]
    }

See also

Inputs description

RATPinputs.RATP_vegetation(parameters, angle_distrib, reflected)[source]

Initialise a RATP Vegetation object from LightVegeManager input datas

Parameters:

parameters (dict) – RATP parameters from inputs of LightVegeManager
angle_distrib (dict) – leaf angle distribution
reflected (bool) – if the user wishes to activate reflected radiations

Returns:

Vegetation types contains clumoing effect ratio, leaf angle distribution and reflectance/transmittance of leaves for each specy

Return type:

PyRATP.pyratp.vegetation.Vegetation

RATPinputs.RATP_meteo(energy, day, hour, coordinates, parunit, truesolartime, direct, diffus)[source]

Initialise a RATP MicroMeteo object from LightVegeManager input parameters

Parameters:

energy (float) – input ray energy
day (int) – input day
hour (int) – input hour
coordinates (list) – [latitude, longitude, timezone]
parunit (string) – unit of energy argument, “micromol.m-2.s-1” or else
truesolartime (bool) – activates true solar time or local time to compute sun position
direct (bool) – if direct rays are activated
diffus (bool) – if diffuse rays are activated

Returns:

input meteorological data at current time step

Return type:

PyRATP.pyratp.micrometeo.MicroMeteo

RATPinputs.RdRsH(Rg, DOY, heureTU, latitude)[source]: fraction diffus/Global en fonction du rapport Global(Sgd)/Extraterrestre(Sod)- pas de temps horaire

`VTK` module

VTK 

Writes VTK files from LightVegeManager geometry and lighting data. Used for visualisation We recommend the software Paraview for visualisation

VTK.VTKtriangles(trimesh, var=[], varname=[], filename='')[source]

Writes VTK files from a triangulation mesh. Possibility to associate physical values to the triangles

Parameters:

trimesh (dict of list) –
triangles mesh aggregated by indice elements
```
{ id : [triangle1, triangle2, ...]}
```
var (list of list) –
list of physical values associated to each triangle. Each element of var is a physical value for each triangle. Then, for n triangles and m values, var looks like:
```
var = [[var1_1, ..., var1_n], ..., [varm_1, ..., varm_n]]
```
varname (lits of string) – list of variable names
filename (string) – name and path for the output file

VTK.VTKline(start, end, filename)[source]

Writes a VTK file representing a line

Parameters:

start (list) – starting point [x, y, z] of the line
end (list) – ending point [x, y, z] of the line
filename (string) – name and path for the output file

VTK.ratp_prepareVTK(ratpgrid, filename, columns=[], df_values=None)[source]

Sets and prepare data to write a voxel grid in VTK format from a RATP grid

Possibility to sets physical values to each voxel. Otherwise, it will assign leaf area density for each voxel.

Then, it runs :func:VTKvoxels to write a VTK file with the grid of voxels.

Parameters:

ratpgrid (pyratp.grid) – RAPT grid of voxels
filename (string) – name and path for the output file
columns (list, optional) – list of columns name of df_values to associate to each voxel, defaults to []
df_values (pandas.Dataframe, optional) – dataframe with a "Voxel" and a "VegetationType" columns, matching ratpgrid. It stores physical values associated to each voxel that you want to print, defaults to None

VTK.VTKvoxels(grid, datafields, varnames, nomfich)[source]

Writes a VTK file with a grid of voxels and associated physical values.

Display Voxels colored by variable with Paraview

RATP Grid is written in VTK Format as a structured grid

Parameters:

grid (pyratp.grid) – the RATP grid
datafields (list of list) –
a list of 3 arrays composed of the a RATP variable to be plotted, corresponding entities, and Voxel ID
- [0] : kxyz (numpy.array)
- [1] : entities (numpy.array)
- [2, …, n] : variable_0, … variable_n-2 (numpy.array)
varnames (list of string) – name of the variable to be plotted
nomfich (string) – the VTK filename and path

VTK.PlantGL_to_VTK(scenes, path, i=0, in_unit='m', out_unit='m')[source]

Directly converts a list plantGL scenes to a single VTK file The routine aggregates all the scenes in one global triangulation and then calls :func:VTKtriangles Possbility to rescale measure unit scenes

Parameters:

scenes (lits of plantgl.Scene) – list of scenes to be written
path (string) – path of the file. File name is set by default with "triangles_plantgl_"+str(i)+".vtk"
i (int, optional) – id of the file. Used if you want to batch a large number of scenes, defaults to 0
in_unit (str, optional) – input measure unit, defaults to “m”
out_unit (str, optional) – output measure unit, defaults to “m”

Raises:

ValueError – in_unit or out_unit not a valid entry upon the listed measure units

`basicgeometry` module

basicgeometry 

Provides basic geometric operations in 3D used by LightVegeManager. Vectors are represented by their cartesian coordinates in a 3-tuple of floats such as v = (x, y, z) Triangles are a list of 3 vectors representing its vertices

basicgeometry.crossproduct(v1, v2)[source]

Crossproduct between two vectors v1^v2

Parameters:

v1 (3-tuple) – vector 1
v2 (3-tuple) – vector 2

Returns:

crossproduct

Return type:

3-tuple

basicgeometry.middle(v1, v2)[source]

Middle point between v1 and v2

Parameters:

v1 (3-tuple) – vector 1
v2 (3-tuple) – vector 2

Returns:

middle point \(p = (v1+v2)/2\)

Return type:

3-tuple

basicgeometry.triangle_normal(triangle)[source]

Computes normal of an oriented triangle (3D)

Note

a triangle is [(x1,y1,z1),(x2,y2,z2),(x3,y3,z3)]

Parameters:: triangle (list) – triangle represented by its 3 vertices
Returns:: normalized vector
Return type:: 3-tuple

basicgeometry.triangle_elevation(triangle)[source]

Computes normal elevation of triangle

Note

a triangle is [(x1,y1,z1),(x2,y2,z2),(x3,y3,z3)]

Parameters:: triangle (list) – triangle represented by its 3 vertices
Returns:: angle in degree elevation starts from ground to normal vector must be between 0 and 90°
Return type:: float

basicgeometry.triangle_area(triangle)[source]

triangle area

Note

a triangle is [(x1,y1,z1),(x2,y2,z2),(x3,y3,z3)]

Parameters:

triangle (list) – triangle represented by its 3 vertices

Returns:

area

Note

algorithm is a copy of _surf in alinea.caribu.caributriangleset

Return type:

float

basicgeometry.triangle_barycenter(triangle)[source]

triangle barycenter

Note

a triangle is [(x1,y1,z1),(x2,y2,z2),(x3,y3,z3)]

Parameters:: triangle (list) – triangle represented by its 3 vertices
Returns:: isobarycenter \((s1 + s2 + s3)/3\)
Return type:: float

basicgeometry.rescale(triangles, h)[source]

Multiplies all triangle vertices by a ratio h

Note

a triangle is [(x1,y1,z1),(x2,y2,z2),(x3,y3,z3)]

Parameters:

triangles (list of list) – list of triangles in the same format as below
h (float) – ratio

Returns:

list of triangles with each triangle from input rescaled by h

Return type:

list of list

example

>>> triangles = [[(0,0,0), (0,1,0), (0,1,1)], [(0,0,1), (0,0,0), (1,0,1)]]
>>> rescale(triangles, 3)
[[(0,0,0), (0,3,0), (0,3,3)], [(0,0,3), (0,0,0), (3,0,3)]]

basicgeometry.translate(triangles, tvec)[source]

Moves a list of triangles with a translation of vector tvec

Note

a triangle is [(x1,y1,z1),(x2,y2,z2),(x3,y3,z3)]

Parameters:

triangles (list of list) – list of triangles in the same format as below
tvec (3-tuple) – vector

Returns:

list of triangles with each triangle from input translated by tvec

Return type:

list of list

example

>>> triangles = [[(0,0,0), (0,1,0), (0,1,1)], [(0,0,1), (0,0,0), (1,0,1)]]
>>> tvec = (3,0,1)
>>> translate(triangles, tvec )
[[(3,0,1), (3,1,1), (3,1,2)], [(3,0,2), (3,0,1), (4,0,2)]]

basicgeometry.zrotate(triangles, omegadeg)[source]

Rotates a list of triangles in the xy plane from an angle

Note

a triangle is [(x1,y1,z1),(x2,y2,z2),(x3,y3,z3)]

Parameters:

triangles (list of list) – list of triangles in the same format as below
omegadeg (float) – angle in degree

Returns:

list of triangles with each triangle from input rotated around z axis by omegadeg

Return type:

list of list

example

>>> triangles = [[(0,0,0), (0,1,0), (0,1,1)], [(0,0,1), (0,0,0), (1,0,1)]]
>>> zrotate(triangles, 90 )
[[(0,0,0), (-1,0,0), (-1,0,1)], [(0,0,1), (0,0,0), (0,1,1)]]

`buildRATPscene` module

buildRATPscene 

Creation of a PyRATP.grid from inputs. The following functions create and initialize a grid from either a triangles mesh, a l-egume grid or an empty geometric input

The argument parameters refers to one the three inputs dict of LightVegeManager. It is structured as so:

ratp_args = {
        # Grid specifications
        "voxel size" : [dx, dy, dz],
        "voxel size" : "dynamic",

        "origin" : [xorigin, yorigin, zorigin],
        "origin" : [xorigin, yorigin],

        "number voxels" : [nx, ny, nz],
        "grid slicing" : "ground = 0."
        "tesselation level" : int

        # Leaf angle distribution
        "angle distrib algo" : "compute global",
        "angle distrib algo" : "compute voxel",
        "angle distrib algo" : "file",

        "nb angle classes" : int,
        "angle distrib file" : filepath,

        # Vegetation type
        "soil reflectance" : [reflectance_band0, reflectance_band1, ...],
        "reflectance coefficients" : [reflectance_band0, reflectance_band1, ...],
        "mu" : [mu_scene0, mu_scene1, ...]
    }

See also

For more details Inputs description

buildRATPscene.extract_grid_origin(parameters, minmax)[source]

Create grid origin from either input parameters or from the scene

Parameters:

parameters (dict) – RATP parameters from inputs of LightVegeManager
minmax ([3-tuple, 3-tuple]) – list of mininuml point and maximum point in a triangles mesh

Returns:

origin of the grid depending of input parameters and size of the mesh

Return type:

3-tuple

buildRATPscene.build_RATPscene_from_trimesh(trimesh, minmax, triLmax, matching_ids, parameters, coordinates, reflected, infinite, stems_id=None, nb_input_scenes=0, fullgrid=False)[source]

Build a RATP grid from a triangles mesh.

Parameters:

trimesh (dict) – triangles mesh aggregated by indice elements .. code-block:: { id : [triangle1, triangle2, …]}
minmax ([3-tuple, 3-tuple]) – list of mininuml point and maximum point in a triangles mesh
triLmax (float) – longest side of all the triangles in trimesh
matching_ids (dict) – dict that matches new element indices in trimesh with specy indice and input element indice .. code:: matching_ids = { new_element_id : (input_element_id, specy_id)}
parameters (dict) – RATP parameters from inputs of LightVegeManager
coordinates (list) – [latitude, longitude, timezone]
reflected (bool) – if the user wishes to activate reflected radiations
infinite (bool) – if the user wishes to activate infinitisation of the grid
stems_id (list of 2-tuple, optional) – list of potential stems element in the input scenes, defaults to None
nb_input_scenes (int, optional) – number of input scenes in the geometry dict, defaults to 0

Returns:

It returns 3 objects:

ratpgrid
pyratp.grid filled with areas of triangles in trimesh and input parameters
matching_tri_vox
dict where key is a triangle indice and value the matching voxel indice where the barycenter of the triangle is located
distrib
dict with a "global" key and if ["angle distrib algo"] = "compute voxel" a second entry where key is "voxel"

value for "voxel" is a numpy.array of dimension (numberofvoxels,numberofentities,numberofclasses)

value for "global" is a list of numberofentities list of numberofclasses elements

Return type:

pyratp.grid, dict, dict

buildRATPscene.build_RATPscene_empty(parameters, minmax, coordinates, infinite)[source]

Build a RATP grid from an empty geometric input

Parameters:

parameters (dict) – RATP parameters from inputs of LightVegeManager
minmax ([3-tuple, 3-tuple]) – list of mininuml point and maximum point in a triangles mesh
coordinates (list) – [latitude, longitude, timezone]
infinite (bool) – if the user wishes to activate infinitisation of the grid

Returns:

ratpgrid: pyratp.grid sets with input parameters
distrib: dict with one entry "global" : [1.]

Return type:

pyratp.grid, dict

buildRATPscene.legumescene_to_RATPscene(legumescene, parameters, coordinates, reflected, infinite)[source]

Creates a RATP grid of voxels from a l-egume grid format

Parameters:

legumescene (dict) –
l-egume grid represented by a dict with two entries:
- "LA": equivalent to m_lais in l-egume, a numpy.array of dimension (nent, nz, ny, nx) which represents leaf area in each voxel for each specy
- "distrib": equivalent to ls_dif in l-egume, a numpy.array of dimension (nent, nclasses) which represents the global leaf angle distribution for each input specy
Note

legumescene is the only input geometric scene which can handle several species
parameters (dict) – RATP parameters from inputs of LightVegeManager
coordinates (list) – [latitude, longitude, timezone]
reflected (bool) – if the user wishes to activate reflected radiations
infinite (bool) – if the user wishes to activate infinitisation of the grid

Returns:

It returns 3 objects

ratpgrid : pyratp.grid filled with areas of triangles in trimesh and input parameters
distrib : dict with only a "global" key, value for "global" is a list of numberofentities list of numberofclasses elements
nb0 : number of empty layers between top canopy and maximum layer in legumescene

Return type:

pyratp.grid, dict, int

buildRATPscene.concatene_legumescenes(scenes)[source]

`defaultvalues` module

defaultvalues 

Default for simulation fixed parameters These parameters are sets in LightVegeManager if the user did not precise thoses inputs

defaultvalues.default_LightVegeManager_inputs()[source]

returns default parameters for LightVegeManager constructor __init__

Returns:: environment and light model parameters
Return type:: dict, dict

`leafangles` module

leafangles 

Handles leaf angle distribution, both in its dynamic computing or reading a file

An angle distribution is a list of n elements, where n is the number of angle class between 0 and 90°. Each element of this list is a percentage for leaves to be oriented from 0 to 90/n degree. The sum of all the list entries must equal 1.

leafangles.read_distrib_file(path, numberofentities)[source]

Reads global leaf angle distribution in a file the file must matches the format : one specy distribution per line each percentage separated by a coma ‘,’

example

0.1382,0.1664,0.1972,0.1925,0.1507,0.0903,0.0425,0.0172,0.005
0.3,0.1,0.15,0.2,0.05,0.2

Parameters:

path (string) – path to the file
numberofentities (int) – number of species, aka numbre of lines in the file

Returns:

distribution for each specy, number of entries on one line

Return type:

list of list

leafangles.compute_distrib_globale(trimesh, matching_ids, numberofclasses)[source]

Calculation of a global leaf angle distribution from a triangle mesh

Parameters:

trimesh (dict) – triangles mesh aggregated by indice elements { id : [triangle1, triangle2, ...]}
matching_ids (dict) –
dict that matches new element indices in trimesh with specy indice and input element indice, matching_ids = { new_element_id : (input_element_id, specy_id)}

this dict allows us to look how species there is the inputs geometric data
numberofclasses (int) – number angle class wanted between 0 and 90 degree

Returns:

a leaf angle distribution for each specy. Each distribution is a length numberofclasses the distribution is computed on all trimesh

Return type:

list of list

leafangles.compute_distrib_voxel(trimesh, matching_ids, numberofclasses, numberofvoxels, matching_tri_vox)[source]

Calculation of a local leaf angle distribution from a triangle mesh on each voxel of a grid

Parameters:

trimesh (dict) – triangles mesh aggregated by indice elements { id : [triangle1, triangle2, ...]}
matching_ids (dict) – dict that matches new element indices in trimesh with specy indice and input element indice, matching_ids = { new_element_id : (input_element_id, specy_id)} this dict allows us to look how species there is the inputs geometric data
numberofclasses (int) – number angle class wanted between 0 and 90 degree
numberofclasses – number of non empty voxels in the grid
matching_tri_vox (dict) – dict where key is a triangle indice and value the matching voxel indice where the barycenter of the triangle is located

Returns:

array of dimension [number of voxels][number of species][number of angle classes] i.e. it returns for each voxel a leaf angle distribution for each specy

Return type:

numpy.array

`outputs` module

outputs 

Manages and reformat output results from the light models in pandas.Dataframe with similar columns names.

Light models managed in this module:

RATP

CARIBU

Column names for voxels:

'VegetationType': id of the specy

'Iteration': RATP can handle multiple iterations in inputs, but it is not properly exploited in LightVegeManager yet

'Day': input day if LightVegeManager

'Hour': input hour if LightVegeManager

'Voxel': index of current voxel

'Nx': index in grid following x axis, corresponds to pyrapt.grid.numx

'Ny': index in grid following y axis, corresponds to pyrapt.grid.numy

'Nz': index in grid following z axis, corresponds to pyrapt.grid.numz

'ShadedPAR': shaded energy in the current voxel, 0 if no direct light in the input

'SunlitPAR': sunlit energy

'ShadedArea': leaf area in voxel which is shaded

'SunlitArea': leaf area in voxel which is sunlit

'Area': total leaf area in the voxel

'PARa': ( ShadedPAR * ShadedArea + SunlitPAR * SunlitArea ) / ( ShadedArea + SunlitArea )

'Intercepted': relative portion of input rays intercepted by the voxel

'Transmitted': relative portion of input rays leaving out the voxel

Column names for triangles:

'VegetationType': id of the specy

'Day': input day if LightVegeManager

'Hour': input hour if LightVegeManager

'Triangle': indice of the triangle

'Organ': element where the triangle belongs

if ligh model is CARIBU:

'Area': area of the triangles

for each bandwidth in the inputs you have two entries:

band + " Eabs": energy absorbed by the triangle

band + " Ei": energy intercepted by the triangle

If light model is RATP:

'Area': area of total leaf area in the voxel where the triangle is located

'primitive_area': area of the triangle

'Voxel': index of the voxel where the triangle is located

'Nx': index in grid following x axis, corresponds to pyrapt.grid.numx

'Ny': index in grid following y axis, corresponds to pyrapt.grid.numy

'Nz': index in grid following z axis, corresponds to pyrapt.grid.numz

'ShadedPAR': shaded energy in the current voxel

'SunlitPAR': sunlit energy, 0 if no direct light in the input

'ShadedArea': leaf area in voxel which is shaded

'SunlitArea': leaf area in voxel which is sunlit

'PARa': ( ShadedPAR * ShadedArea + SunlitPAR * SunlitArea ) / ( ShadedArea + SunlitArea )

'Intercepted': relative portion of input rays intercepted by the voxel

'Transmitted': relative portion of input rays leaving out the voxel

Column names for elements:

'Day': input day if LightVegeManager

'Hour': input hour if LightVegeManager

'Organ': id of current element

"VegetationType": id of the specy

"Area": area of the element (sum of all triangles belonging to current element)

if light model is CARIBU, for each bandwidth in the optical inputs you have two entries:

band + " Eabs": energy absorbed by the element, integrated on all triangles belonging to current element

band + " Ei": energy intercepted by the triangle, integrated on all triangles belonging to current element

if light model is RATP, the following entries are integrated on all triangles belonging to current element with E, current element, t triangles in E and V an entry: \(\frac{\sum_{t \in E} area_t * V_t}{area_E}\)

"PARa"

"Intercepted"

"Transmitted"

"SunlitPAR"

"SunlitArea"

"ShadedPAR"

"ShadedArea"

outputs.out_ratp_empty_grid(day, hour)[source]

Returns an empty dataframe results for RATP

Parameters:

day (int) – day of simulation
hour (int) – hour of simulation

Returns:

returns a dataframe with all the keys expected with a RATP simulation but results are empty used if input geometry is empty

Return type:

pandas.DataFrame

outputs.out_ratp_voxels(ratpgrid, res, parunit)[source]

Converts RATP results to pandas dataframe compared to the voxels

Parameters:

ratpgrid (pyratp.grid) – RATP grid with voxels informations
res (pyratp.ratp.out_rayt) – output table of RATP
parunit (string) –
energy unit of input

RATP expects W.m-2 in input and return results in µmol.s-1.m-2. if parunit="W.m-2" the outputs is converted to W.m-2, otherwise results are in µmol.s-1.m-2

Returns:

res.T converted in a pandas Dataframe with voxels relative columns. The soil is not part of the results

Return type:

pandas.DataFrame

outputs.out_ratp_triangles(trimesh, matching_ele_ent, matching_tr_vox, voxels_outputs)[source]

Converts RATP results to pandas dataframe compared to the triangles (and voxels)

Parameters:

trimesh (dict) – triangles mesh aggregated by indice elements .. code-block:: { id : [triangle1, triangle2, …]}
matching_ele_ent (dict) – dict that matches new element indices in trimesh with specy indice and input element indice, .. code:: matching_ids = { new_element_id : (input_element_id, specy_id)}
matching_tr_vox (dict) – dict where key is a triangle indice and value the matching voxel indice where the barycenter of the triangle is located
voxels_outputs (pandas.Dataframe) – output of :func:out_ratp_voxels

Returns:

output of :func:out_ratp_voxels merged with associated triangles

Return type:

pandas.Dataframe

outputs.out_ratp_elements(matching_ele_ent, reflected, reflectance_coef, trianglesoutputs)[source]

If trimesh is not empty, aggregates RATP results by element (keys in dict trimesh)

Parameters:

matching_ele_ent (dict) – dict that matches new element indices in trimesh with specy indice and input element indice, .. code:: matching_ids = { new_element_id : (input_element_id, specy_id)}
reflected (bool) – if the user wishes to activate reflected radiations
reflectance_coef (list of list) – coefficient for each specy and each input bandwidth
trianglesoutputs (pandas.Dataframe) – output of :func:out_ratp_triangles

Returns:

dataframe integrated on element informations

Return type:

pandas.Dataframe

outputs.out_caribu_mix(rdrs, c_scene_sun, c_scene_sky, raw_sun, aggregated_sun, raw_sky, aggregated_sky, issensors, issoilmesh)[source]

Mix diffuse and direct rays results according to a ratio rdrs

Parameters:

rdrs (float) – Spitters’s model estimating for the diffuse:direct ratio
c_scene_sun (CaribuScene) – CaribuScene with direct lighting computed (from a sun)
c_scene_sky (CaribuScene) – CaribuScene with diffuse lighting computed (from a sky)
raw_sun (dict of dict) – results of c_scene_sun for triangles
aggregated_sun (dict of dict) – results of c_scene_sun aggregated by element
raw_sky (dict of dict) – results of c_scene_sky for triangles
aggregated_sky (dict of dict) – results of c_scene_sky aggregated by element
issensors (bool) – if option virtual sensors is activated
issoilmesh (bool) – if option soil mesh is activated

Returns:

if sensors is activated, it extracts its results from aggregated_sun and aggregated_sky

if soilmesh is activated, it extracts its results from c_scene_sun and c_scene_sky

then it mixes raw, aggregated, virtual sensors and soil energy results such as

result = rdrs * diffuse_result + (1 - rdrs) * direct_result

Return type:

dict of dict, dict of dict, dict of list, dict of float

outputs.out_caribu_nomix(c_scene, aggregated, issensors, issoilmesh)[source]

Extracts only sensors and soilmesh results if activated

Parameters:

c_scene (CaribuScene) – instance of CaribuScene containing geometry, light source(s), opt etc…
aggregated (dict of dict) – result of CaribuScene.run
issensors (bool) – if option virtual sensors is activated
issoilmesh (bool) – if option soil mesh is activated

Returns:

extracts sensors results from aggregated and soil energy from c_scene

Return type:

dict, dict

outputs.out_caribu_elements(day, hour, trimesh, matching_ids, aggregated, sun_up, caribu_triangles={})[source]

Converts aggregated in a pandas.Dataframe following indices in LightVegeManager

Parameters:

day (int) – day of simulation
hour (int) – hour of simulation
trimesh (dict) – triangles mesh aggregated by indice elements .. code-block:: { id : [triangle1, triangle2, …]}
matching_ele_ent (dict) – dict that matches new element indices in trimesh with specy indice and input element indice, .. code:: matching_ids = { new_element_id : (input_element_id, specy_id)}
aggregated (dict of dict) – result of CaribuScene.run
sun_up (bool) – if sun elevation is > 2° and direct rays are > 0 W.m²

Returns:

aggregated results rearrange in a Dataframe with element correspondance in LightVegeManager

Return type:

pandas.Dataframe

outputs.out_caribu_triangles(day, hour, trimesh, matching_ids, raw, sun_up)[source]

Converts raw in a pandas.Dataframe following simulation datas

Parameters:

day (int) – day of simulation
hour (int) – hour of simulation
trimesh (dict) – triangles mesh aggregated by indice elements .. code-block:: { id : [triangle1, triangle2, …]}
matching_ele_ent (dict) – dict that matches new element indices in trimesh with specy indice and input element indice, .. code:: matching_ids = { new_element_id : (input_element_id, specy_id)}
raw (dict of dict) – triangles results from CaribuScene.run
sun_up (bool) – if sun elevation is > 2° and direct rays are > 0 W.m²

Returns:

triangle results rearrange in a Dataframe

Return type:

pandas.Dataframe

outputs.out_caribu_sensors(day, hour, sensors, matching_sensors_species)[source]

Converts raw in a pandas.Dataframe following simulation datas

Parameters:

day (int) – day of simulation
hour (int) – hour of simulation
sensors (dict) – lighting results for each virtual sensors in caribu
matching_sensors_species (dict) – dict that match each sensor with a plant specy

Returns:

sensors results rearrange in a Dataframe

Return type:

pandas.Dataframe

`plantGL` module

plantGL 

visualisation plantGL

plantGL.cscene_to_plantGLScene_stems(cscene, stems_id=None, matching_ids={})[source]

Transform a triangles mesh to a plantGL scene, whith a color difference between leaves and stems

Parameters:

cscene (dict of list) – LightVegeManager triangulations mesh
stems_id (list of tuple, optional) – list of tuple (element_id, specy_id), defaults to None
matching_ids (dict of tuple, optional) – dict that matches new element indices in trimesh with specy indice and input element indice, defaults to {} matching_ids = { new_element_id : (input_element_id, specy_id)}

Returns:

cscene in plantGL scene format with leaves in green and stems in brown

Return type:

plantGL Scene

plantGL.cscene_to_plantGLScene_light(cscene, outputs={}, column_name='par Ei')[source]

Transform a triangles mesh to a plantGL scene, colors represent lightint results from blue to red

Parameters:

cscene (dict of list) – LightVegeManager triangulations mesh
outputs (Pandas.Dataframe, optional) – outputs results from LightVegeManager, defaults to {}
column_name (str, optional) – name of the value to plot, defaults to “par Ei”

Returns:

cscene in plantGL scene format with a color from blue to red

Return type:

plantGL Scene

plantGL.ratpgrid_to_plantGLScene(ratpgrid, transparency=0.0, plt_cmap='Greens', outputs={})[source]

Transform a RATP grid mesh to a plantGL scene Colors can either follows leaf area or lighting values

Parameters:

ratpgrid (pyratp.grid) – grid of voxels in RATP format
transparency (float, optional) – transparency value of the voxels from 0 to 1, defaults to 0.
plt_cmap (str, optional) – name of the colormap to color the voxels, defaults to “Greens”
outputs (pandas.Dataframe, optional) – lighting results from LightVegeManager, defaults to {}

Returns:

ratpgrid in plantGL scene

Return type:

plantGL Scene

`sky` module

sky 

Build a sky from LightVegeManager input informations

Possible sky options:

"turtle46" : soc sky composed by 46 directions in a turtle shape
filepath : string indicating a file path
[nb_azimut, nb_zenith, "soc" or "uoc"] : build a sky with a custom number of directions

output :

with RATP : pyratp.skyvault
with CARIBU : [(weight, (dir[0], dir[1], dir[2])), … ]

Sky file is in RATP format

sky.ratpformat_to_caribuformat(az, h, pc, rad=True)[source]

Converts sky informations from RATP format to CARIBU format

Parameters:

az (list) – azimuts of each sky direction (degree)
h (list) – elevation of each sky direction (degree)
pc (list) – perez weight of each sky direction

Returns:

direction vectors and weights for each sky direction list of (weight, (x, y, z)) vector is from sky to ground

Return type:

list of tuple

sky.caribuformat_to_ratpformat(directions)[source]

Converts CARIBU format to RATP sky format

Parameters:

directions (list of tuples) – list of all each sky directions, such as one direction is (perez coeff, (x, y, z)) where vector looks from sky to floor

Returns:

pc : perez coefficients for each direction
az : azimut of each direction, x+ = 0.
h : elevation of each direction

:rtype:list, list, list

sky.RATPsky(skytype)[source]

Creates a pyratp.skyvault

Parameters:: skytype (string or list) – the environment[“sky”] from the LightVegeManager inputs. It is either: * "turtle46" * a filepath * [nb_azimut, nb_elevation, “soc” or “uoc”], nb_azimut is the number of azimut directions and nb_elevation the number of zenital directions for cutting out the sky
Raises:: ValueError – if skytype is not one of the curretn 3 possibilities
Returns:: a sky in RATP format
Return type:: pyratp.skyvault

sky.CARIBUsky(skytype)[source]

Build a sky in CARIBU format

Parameters:

skytype (string or list) –

the environment[“sky”] from the LightVegeManager inputs. It is either:

"turtle46"
a filepath
[nb_azimut, nb_elevation, “soc” or “uoc”], nb_azimut is the number of azimut directions and nb_zenith the number of zenital directions for cutting out the sky

Raises:

ValueError – if skytype is not one of the curretn 3 possibilities

Returns:

a list of the directions representing the sky. each entry of the list is a tuple (weight, vector), where weight is a float for the weight the direction and vector, a tuple (x, y, z), representing the position of the sky direction, from sky to the ground

Return type:

list of tuple

sky.discrete_sky(n_azimuts, n_zeniths, sky_type)[source]

Cuts out a sky following input number of directions

Parameters:

n_azimuts (int) – number of azimut directions of the sky
n_zeniths (int) – number of elevations directions of the sky
sky_type (string) – "soc" or "uoc"

Returns:

4 output lists of length n_azimuts * n_zeniths

ele: elevations in degrees (angle soil to sky)
azi: azimuts in degrees
omega: solid angle of directions
pc: relative contribution of directions to incident diffuse radiation

Return type:

list, list, list, list

`stems` module

stems 

Manages stems element (opaque)

stems.extract_stems_from_MTG(MTG, entity_id)[source]

Extracts stems element from a MTG table

Parameters:

MTG (openalea.mtg.mtg.MTG) – MTG table descripting plant elements
entity_id (int) – indice of the corresponding geometric scene of the MTG table scene in the LightVegeManager inputs

Returns:

stems is a list where each entry is a tuple (element indice, entity_id)

Return type:

list of tuple

stems.manage_stems_for_ratp(stems_id, matching_ids, ratp_parameters)[source]

Adds a specy to separate stems from leaves in vegetation parameters

Parameters:

stems_id (list of tuple) – list of tuple (element_id, specy_id)
matching_ids (dict) – dict that matches new element indices in trimesh with specy indice and input element indice matching_ids = { new_element_id : (input_element_id, specy_id)}
ratp_parameters (dict) – RATP parameters from inputs of LightVegeManager

Raises:

ValueError – if too many stems elements are identified comparing to the total number of elements cumulated over all species

`sun` module

sun 

Build a sun respecting each light model format

For computing the sun position you can either use CARIBU or RATP algorithm, which slightly change in the process

sun.ratp_sun(day, hour, coordinates, truesolartime)[source]

Converts output RATP sundirection routine to CARIBU light format

Parameters:

day (int) – input day
hour (int) – input hour
coordinates (list) – [latitude, longitude, timezone]
truesolartime (bool) – activates true solar time or local time to compute sun position

Returns:

sun direction in a tuple with cartesian coordinates (x,y,z), vector is oriented from sky to ground

Return type:

tuple

sun.caribu_sun(day, hour, coordinates, truesolartime)[source]

Compute sun direction from CARIBU algorithm

Parameters:

day (int) – input day
hour (int) – input hour
coordinates (list) – [latitude, longitude, timezone]
truesolartime (bool) – activates true solar time or local time to compute sun position

Returns:

sun direction in a tuple with cartesian coordinates (x,y,z), vector is oriented from sky to ground

Return type:

tuple

sun.print_sun(day, hour, coordinates, truesolartime)[source]

Prints sun position ouputs from RATP and CARIBU algorithm with the same inputs

Parameters:

day (int) – input day
hour (int) – input hour
coordinates (list) – [latitude, longitude, timezone]
truesolartime (bool) – activates true solar time or local time to compute sun position

`tesselator` module

tesselator 

Handles tesselation of a triangulation, the subdivision of triangulation. The tesselation was initially made to have a better matching of a triangle mesh in a grid of voxels and avoid triangle to be located in several voxels

Tesselation operates as a recursive function until a certain level is reached

tesselator.whichvoxel(p, mygrid)[source]

Returns in which voxel p is located

Parameters:

p (list or tuple) – 3D vector located in the grid
mygrid (pyratp.grid) – RATP grid

Returns:

returns the voxels where p is located in a list [kx, ky, kz] where ki is the indice voxel on each axis, [0, 0, 0] is origin voxel

Return type:

list

tesselator.samevoxel(voxels)[source]

Check if all voxels in list voxels are the same

Parameters:: voxels (list) – list of voxels in format [kx, ky, kz]
Returns:: if all elements of voxels are the same
Return type:: bool

tesselator.tesselate(mygrid, triangle)[source]

Check if the triangle is strictly inside a voxel or between several voxels. If so, it cuts out triangle in 4 smaller triangles.

Parameters:

mygrid (pyratp.grid) – RATP voxels grid
triangle (list of tuple) – triangle represented by its 3 vertices triangle = [(x1, y1, z1), (x2, y2, z2), (x3, y3, z3)]

Returns:

if the triangle is inside a voxel, it returns the input triangle in a 1-list
else if the triangle is between several voxels, it cuts out triangle in four smaller triangles from its vertices and barycenter

Return type:

list of triangle

tesselator.tesselate2(triangle)[source]

Same as :func:tesselate but without the grid matching

Parameters:: triangle (list of tuple) – triangle represented by its 3 vertices triangle = [(x1, y1, z1), (x2, y2, z2), (x3, y3, z3)]
Returns:: it cuts out triangle in four smaller triangles from its vertices and barycenter
Return type:: list of triangle

tesselator.iterate_trianglesingrid(triangle, mygrid, level, levelmax, triangles_shape)[source]

Recursion on a triangle, while its subdivision doesn’t match an RATP grid or exceed a certain level of tesselation

Parameters:

triangle (list of tuple) – triangle represented by its 3 vertices triangle = [(x1, y1, z1), (x2, y2, z2), (x3, y3, z3)]
mygrid (pyratp.grid) – RATP voxels grid
level (int) – current level of tesselation, i.e. how many times we cut out the initial triangle
levelmax (int) – final level of tesselation to not be exceeded
triangles_shape (list of triangles) – list of triangles used to stock new triangles or input triangle if no tesselation is computed

Returns:

triangles_shape updates with input triangle or new triangles if tesselation was activated

Return type:

list of triangles

tesselator.iterate_triangles(triangle, level, levelmax, triangles_shape)[source]

Subdivide a triangle until its tesselation reaches levelmax. It stocks the new triangles in triangle_shape Recursive function

Parameters:

triangle (list of tuple) – triangle represented by its 3 vertices triangle = [(x1, y1, z1), (x2, y2, z2), (x3, y3, z3)]
level (int) – current level of tesselation, i.e. how many times we cut out the initial triangle
levelmax (int) – final level of tesselation to not be exceeded
triangles_shape (list of triangles) – list of triangles used to stock new triangles or input triangle if no tesselation is computed

Returns:

triangles_shape updates with new triangles from tesselation

Return type:

list of triangles

`transfer` module

transfer 

Handles transfer of LightVegeManager results to plant Models.

Currently, it manages CN-Wheat and l-egume. Only l-egume needs additionnal processes to converts Dataframe results in a compatible format.

l-egume expects the absorb PAR either per plant or locally following a grid of voxels, and the transmitted PAR locally following a grid of voxels. Here, we will convert and transform results for CARIBU and RATP to those l-egume format.

transfer.transfer_ratp_legume(m_lais, energy, ratp_grid, voxels_outputs, nb0, epsilon=1e-08)[source]

Transfers LightVegeManager outputs from RATP to l-egume Absorb and transmitted PAR will follow a RATP grid of voxels, matching the dimensions of intern l-egume grid of voxels.

Parameters:

m_lais (numpy.array) – leaf area represented in a numpy.array of dimension [number of species, number of z layers, number of y layers, number of x layers]
energy (float) – input energy
ratp_grid (pyratp.grid) – RATP grid of voxels
voxels_outputs (pandas.Dataframe) – results from LightVegeManager
nb0 (int) – number of empty layers from top of the canopy and maximum z layers in m_lais
epsilon (float) – criteria of minimum intercepted portion of PAR in a non empty voxel

Returns:

two array with lighting informations

res_abs_i: absorb PAR in each voxel for RATP grid of voxels. It has the same dimensions as m_lais

res_trans: transmitted PAR in each voxel, i.e. the energy leaving the voxels from input rays. This value is not dependent on specy

dimensions are (number of z layers, number of y layers, number of x layers)

Return type:

numpy.array, numpy.array

transfer.transfer_caribu_legume(energy, skylayer, id, elements_outputs, sensors_outputs, sensors_dxyz, sensors_nxyz, m_lais, list_invar, list_lstring, list_dicFeuilBilanR, infinite, epsilon)[source]

Transfers LightVegeManager outputs from CARIBU to l-egume We will update list_invar which stores the total intercepted energy for each plant, and return an array storing transmitted energy following the intern grid of voxels in l-egume. To do so, we used virtual sensors in CARIBU to get incoming radiations in selected locations.

Parameters:

energy (float) – input energy
skylayer (int) – number of empty layers from top of the canopy and maximum z layers in m_lais
id (list of int) – list of indices of input scenes associated with l-egume
elements_outputs (pandas.Dataframe) – Dataframe results of elements formatted by :func:outputs.out_caribu_elements
sensors_outputs (dict of list) –
lighting results of virtual sensors form CARIBU in the format for each bandwidth computed,
```
sensors_outputs[band+" Eabs"] = {sensor_id : energy}
sensors_outputs[band+" Ei"] = {sensor_id : energy}
```
sensors_dxyz (list) – size of sides of a voxel in the grid of virtual sensors [dx, dy, dz]
sensors_nxyz (list) – number of sensors in each direction in the grid [nx, ny, nz]
m_lais (numpy.array) – leaf area represented in a numpy.array of dimension [number of species, number of z layers, number of y layers, number of x layers]
list_invar (list of dict) – from l-egume, each element corresponds to an input specy of l-egume. Each element is a dict invar stores instant intern variables of l-egume.
list_lstring (list of dict) – from l-egume, each element corresponds to an input specy of l-egume. Each element is a dict lstring stores the l-system of each plant
list_dicFeuilBilanR (list of dict) – from l-egume, each element corresponds to an input specy of l-egume. Each element is a dict dicFeuiBilanR stores correspondances between voxels grid and each plant
infinite (bool) – if the user wishes to activate infinitisation of the grid
epsilon (float) – criteria of minimum intercepted portion of PAR in a voxel (if res_abs_i is zero, l-egume will crash)

Raises:

ValueError – Virtual sensors and finite scene doesn’t work yet with CARIBU

Returns:

it updates list_invar and its key entries "parap" and "parip", each element if the scipy.array is the sum of all intercepted energy for each plant. This process is a rewrite of calc_paraF in ShootMorpho.py module of l-egume, adapted to LightVegeManager numerotation of triangles
res_trans an array of transmitted energy for each voxel in a grid of dimensions sensors_dxyz * sensors_nxyz

Return type:

numpy.array

`trianglesmesh` module

trianglesmesh 

It builds and handles triangulation mesh.

The main triangulation format in LightVegeManager is the CARIBU format: scene (dict): a {primitive_id: [triangle,]} dict. A triangle is a list of 3-tuples points coordinates. example:

scene = {   # element 0
            0 : [ 
                    [(1,1,1), (0,0,0), (1,2,2)],  # triangle 0 of element 0
                    [(10,10,10), (0,0,0), (10,20,20)] # triangle 1 of element 0
                ] ,

            # element 1
            1 : [
                    [(12,12,12), (10,20,30), (21,22,22)], 
                    [(10,10,10), (10,20,30), (20,20,20)]
                ]
        }

See also

For more details Inputs description

trianglesmesh.triangles_entity(cscene, entity_id, matching_ids)[source]

Return a list of triangles belonging to the specy entity_id

Parameters:

cscene (dict of list) – LightVegeManager triangulations mesh
entity_id (int) – specy indice in matching_ids
matching_ids (dict) –
dict that matches new element indices in cscene with specy indice and input element indice, .. code:: matching_ids = { new_element_id : (input_element_id, specy_id)}

this dict allows us to look how species there is the inputs geometric data

Returns:

list of triangles belonging to entity_id in cscene, a triangle is [(x1, y1, z1), (x2, y2, z2), (x3, y3, z3)]

Return type:

list

trianglesmesh.globalid_to_elementid(cscene, triangleid)[source]

Return the element index in cscene from a global triangle indice, as if triangles were in a list without a sorting by element.

Parameters:

cscene (dict of list) – LightVegeManager triangulations mesh
triangleid (int) – indice from 0 to total number of triangles in cscene

Raises:

IndexError – if triangleid > total number of triangles in cscene

Returns:

element indice where triangleid belongs in cscene

Return type:

int

trianglesmesh.globalid_to_triangle(cscene, triangleid)[source]

Return the corresponding triangle in cscene from a global triangle indice, as if triangles were in a list without a sorting by element.

Parameters:

cscene (dict of list) – LightVegeManager triangulations mesh
triangleid (int) – indice from 0 to total number of triangles in cscene

Raises:

IndexError – if triangleid > total number of triangles in cscene

Returns:

Corresponding triangle in cscene

Return type:

list of tuple

trianglesmesh.compute_area_max(cscene)[source]

Maximum triangle area in a triangulation

Parameters:: cscene (dict of list) – LightVegeManager triangulations mesh
Returns:: maximum triangle area in cscene
Return type:: float

trianglesmesh.compute_minmax_coord(cscene)[source]

Maximum and minimum point in all triangulation mesh

Parameters:: cscene (dict of list) – LightVegeManager triangulations mesh
Returns:: minimum point, maximum point
Return type:: list, list

trianglesmesh.compute_trilenght_max(cscene)[source]

Search for maximum side of an axis oriented voxel where all triangles could fit in

Parameters:: cscene (dict of list) – LightVegeManager triangulations mesh
Returns:: maximum side of an axis oriented voxel where all triangles in cscene could fit in
Return type:: float

trianglesmesh.isatriangle(t)[source]

trianglesmesh.chain_triangulations(scenes)[source]

Aggregates all input geometric scenes in one global triangulation

Current known formats:

plantGL scene

VGX file

CARIBU triangulation format (which is used in LightVegeManager for the global scene)

MTG table with "geometry" identifier

l-egume grid: dict of two entries, leaf area through a voxels grid and leaf angle distribution, for each specy

Only l-egume grid can stores multiple species, otherwise each entry scene must represent one specy

Parameters:

scenes (list) – geometric["scenes"] from LightVegeManager inputs, list of geometric scenes. Scenes can be in different format in the list.

Returns:

it returns 4 objects

complete_trimesh: global triangulation which aggregates all input scenes. It is in CARIBU format

matching_ids: dict which stores correspondances between new element indice, element indice in the input and specy indice

legume_grid: boolean specifing if at least one l-egume grid is among the input scenes

id_legume_scene: indice in the input scenes of a l-egume grid

Return type:

dict of list, dict of list, bool, int

trianglesmesh.vgx_to_caribu(file, id_element)[source]: Reads VGX file and converts them in CARIBU scene format line is a leaf triangle if R column != 42 :param file: path name of the file :type file: string :param id_element: element indice where the triangulation will be stored :type id_element: int :return: triangulation in CARIBU format {id_element : [triangle,]} :rtype: dict of list

trianglesmesh.apply_transformations(cscene, matching_ids, transformations, cscene_unit)[source]

Applies geometric transformations on some part of the triangulation set in input datas Each transformation applies on all triangles from the same input scene.

Parameters:

cscene (dict of list) – LightVegeManager triangulations mesh
matching_ids (dict) –
dict that matches new element indices in cscene with specy indice and input element indice,
```
matching_ids = { new_element_id : (input_element_id, specy_id)}
```
this dict allows us to look how species there is the inputs geometric data
transformations –
dict containing which geometric to apply on which element

Possible transformations:
- ["scenes unit] = {id_scene: unit}
- ["rescale"] = {id_scene: h}
- ["translate"] = {id_scene: vector}
- ["xyz orientation"] = {id_scene: orientation}

id_scene is the index in the input geometric scenes list

Parameters:

cscene_unit (string) – measure unit of cscene

Raises:

ValueError – unit is not in the list ['mm','cm','dm','m','dam','hm','km']
ValueError – unit is not in the list ['mm','cm','dm','m','dam','hm','km']
ValueError – xyz orientation is not one of "x+ = S", "x+ = E", "x+ = W", "x+ = N"

Returns:

cscene with transformations applied to inputs scene parts in the global mesh

Return type:

dict of list

trianglesmesh.create_heterogeneous_canopy(geometrical_model, mtg=None, nplants=50, var_plant_position=0.03, var_leaf_inclination=0.157, var_leaf_azimut=1.57, var_stem_azimut=0.157, plant_density=250, inter_row=0.15, id_type=None, seed=None)[source]

Duplicate a plant in order to obtain a heterogeneous canopy.

Parameters:

nplants (int) – the desired number of duplicated plants
var_plant_position (float) – variability for plant position (m)
var_leaf_inclination (float) – variability for leaf inclination (rad)
var_leaf_azimut (float) – variability for leaf azimut (rad)
var_stem_azimut (float) – variability for stem azimut (rad)
id_type (string) – precise how to set the shape id of the elements : None, plant or organ

Returns:

duplicated heterogenous scene and its domain

Return type:

openalea.plantgl.all.Scene, (float)

trianglesmesh.random_triangle_generator(worldsize=(0, 100), spheresize=(1.0, 1.0), sigma_angle=(3.141592653589793, 3.141592653589793), theta_angle=(0.7853981633974483, 0.6283185307179586))[source]

Generate a random based on parameters

Vertices are generated on a surface of a sphere

Args:: worldsize (tuple, optional): min and max where sphere center can be generated. Defaults to (0,100). spheresize (tuple, optional): mean and std of the sphere size. Defaults to (1.,1.). sigma_angle (tuple, optional): mean and std of the spherical angle on xy plane. Defaults to (math.pi, math.pi). theta_angle (tuple, optional): mean and std of the zenithal angle. Defaults to (math.pi/4, math.pi/5).
Returns:: list of 3 3-tuples: triangles defined by 3 xyz points

`voxelsmesh` module

voxelsmesh 

Builds and handles axis oriented voxels mesh

voxelsmesh.compute_grid_size_from_trimesh(pmin, pmax, dv, grid_slicing=None)[source]

Dynamically compute number of voxels for each axis in the grid The grid is ajusted to be the smallest box containing another mesh

Parameters:

pmin (list) – Minimum point of a mesh [x, y, z]
pmax (list) – Maximum point of a mesh [x, y, z]
dv (list) – size a voxel in each direction [dx, dy, dz]
grid_slicing (string, optional) – possibility to force the ground to be at z=0, defaults to None

Returns:

number of voxels in each direction x, y and z

Return type:

int, int, int

voxelsmesh.tesselate_trimesh_on_grid(trimesh, ratpgrid, levelmax)[source]

Loop on all triangles of a triangulation to tesselate them for better matching a grid of voxels Triangles will subdivide on sides of voxels respecting a certain maximum level

Parameters:

trimesh (dict of list) –
triangles mesh aggregated by indice elements
```
{ id : [triangle1, triangle2, ...]}
```
ratpgrid (pyratp.grid) – RATP grid of voxels
levelmax (int) – maximum level for subdividing triangles

Returns:

a copy of trimesh with subdivided triangles

Return type:

dict of list

voxelsmesh.fill_ratpgrid_from_trimesh(trimesh, matching_ids, ratpgrid, stems_id=None, nb_input_scenes=0)[source]

Fills a RATP grid from a triangulation. It gives barycenters and areas of triangles to update the leaf area density in the corresponding voxel.

Parameters:

trimesh (dict of list) –
triangles mesh aggregated by indice elements
```
{ id : [triangle1, triangle2, ...]}
```
matching_ids (dict) –
dict that matches new element indices in cscene with specy indice and input element indice,
```
matching_ids = { new_element_id : (input_element_id, specy_id)}
```
this dict allows us to look how species there is the inputs geometric data
ratpgrid (pyratp.grid) – RATP grid of voxels
stems_id (list of 2-tuple, optional) – list of potential stems element in the input scenes, defaults to None
nb_input_scenes (int, optional) – number of input geometrical scenes. It can be different with number of species if there is a l-egume grid in the input with several species in it, defaults to 0

Returns:

copy of ratpgrid with leaf area density values from barycenters and areas of the input triangles

Return type:

pyratp.grid

voxelsmesh.fill_ratpgrid_from_legumescene(legumescene, ratpgrid, nb0)[source]

Fills a RATP grid from a l-egume grid It updates ratpgrid.

Parameters:

legumescene (dict) –
l-egume grid represented by a dict with two entries:
- "LA": equivalent to m_lais in l-egume, a numpy.array of dimension (nent, nz, ny, nx) which represents leaf area in each voxel for each specy. nz=0 is the top layer
- "distrib": equivalent to ls_dif in l-egume, a numpy.array of dimension (nent, nclasses) which represents the global leaf angle distribution for each input specy
Note

legumescene is the only input geometric scene which can handle several species
ratpgrid (pyratp.grid) – RATP grid of voxels. nz=0 is the top layer
nb0 (int) – number of empty layers from top of the canopy and maximum z layers in m_lais

voxelsmesh.reduce_layers_from_trimesh(trimesh, pmax, dxyz, nxyz, matching_ids, ids=None)[source]

Number of empty layers in a grid of voxels, from the top of the canopy to the last expected layer. It computes this number from a triangles mesh

Parameters:

trimesh (dict of list) –
triangles mesh aggregated by indice elements
```
{ id : [triangle1, triangle2, ...]}
```
pmax (list) – Maximum point of a mesh [x, y, z]
dxyz (list) – size of sides of a voxel [dx, dy, dz]
nxyz (list) – number of voxels in each direction [nx, ny, nz], nz is the expected number of layers
matching_ids (dict) –
dict that matches new element indices in cscene with specy indice and input element indice,
```
matching_ids = { new_element_id : (input_element_id, specy_id)}
```
this dict allows us to look how species there is the inputs geometric data
ids (list of int, optional) – list of specy indices considered not empty, defaults to None

Returns:

number of empty layers between top of the canopy (represented by trimesh) and nxyz[2]

Return type:

int

LVM module

CARIBUinputs module

RATPinputs module

VTK module

basicgeometry module

example

example

example

buildRATPscene module

defaultvalues module

leafangles module

outputs module

plantGL module

sky module

stems module

sun module

tesselator module

transfer module

trianglesmesh module

voxelsmesh module

`LVM` module

`CARIBUinputs` module

`RATPinputs` module

`VTK` module

`basicgeometry` module

`buildRATPscene` module

`defaultvalues` module

`leafangles` module

`outputs` module

`plantGL` module

`sky` module

`stems` module

`sun` module

`tesselator` module

`transfer` module

`trianglesmesh` module

`voxelsmesh` module