Reference guide#

openalea.caribu.caribu module#

Core pythonic functions to call caribu shell.

openalea.caribu.caribu.encode_labels(materials, species, x_mat=False)[source]#
openalea.caribu.caribu.get_incident(eabs, materials)[source]#

estimate incident light using absorbed light and materials

For asymmetric materials, return a mean estimate

openalea.caribu.caribu.light_string(lights)[source]#

format lights as caribu light file string content

openalea.caribu.caribu.mixed_radiosity(triangles, materials, lights, domain, soil_reflectance, diameter, layers, height, screen_size=1536, sensors=None, debug=False)[source]#

Compute monochrome illumination of triangles using mixed-radiosity model.

Parameters:

  • triangles – (list of list of tuples) a list of triangles, each being defined by an ordered triplet of 3-tuple points coordinates.

  • materials – (list of tuple) a list of materials defining optical properties of triangles A material is a 1-, 2- or 4-tuple depending on its optical behavior. A 1-tuple encode an opaque material characterised by its reflectance A 2-tuple encode a symmetric translucent material defined by a reflectance and a transmittance A 4-tuple encode an asymmetric translucent material defined the reflectance and transmittance of the upper and lower side respectively

  • lights – (list of tuples) a list of (Energy, (vx, vy, vz)) tuples defining light sources Energy is light flux passing through a unit area (scene unit) horizontal plane.

  • domain – (tuple of floats) 2D Coordinates of the domain bounding the scene for its replication. (xmin, ymin, xmax, ymax) scene is not bounded along z axis

  • soil_reflectance – (float) the reflectance of the soil

  • diameter – diameter (scene unit) of the sphere defining the close neighbourhood for local radiosity.

  • layers – vertical subdivisions of scene used for approximation of far contribution

  • height – upper limit of canopy layers (scene unit)

  • screen_size – (int) buffer size for projection images (pixels)

  • sensors – (list of list of tuples) a list of triangles defining virtual sensors

  • debug – (bool) Whether Caribu should be called in debug mode

Returns:

property) properties computed:

  • index(int) : the indices of the input triangles present in outputs ?

  • label(str) : the internal barcode (canlabel) used by caribu (for debuging)

  • area (float): the indiviual areas of triangles

  • Eabs (float): the surfacic density of energy absorbed by the triangles (absorbed_energy / area)

  • Ei (float): the surfacic density of energy incoming on the triangles

  • Ei_inf (float): the surfacic density of energy incoming on the inferior face of the triangle

  • Ei_sup (float): the surfacic density of energy incoming on the superior face of the triangle

  • sensor (dict): a dict with id, area, surfacic density of incoming direct energy and surfacic density of incoming total energy of sensors, if any

Return type:

(dict of str

openalea.caribu.caribu.opt_string(species, soil_reflectance=-1)[source]#

format species as caribu opt file string content

openalea.caribu.caribu.opt_string_and_labels(materials, soil_reflectance=-1)[source]#

format materials as caribu opt file string content and encode label

openalea.caribu.caribu.pattern_string(pattern_tuple)[source]#

format pattern as caribu file string content

openalea.caribu.caribu.radiosity(triangles, materials, lights=((1, (0, 0, -1)),), screen_size=1536, sensors=None, debug=False)[source]#

Compute monochromatic illumination of triangles using radiosity method.

Parameters:

  • triangles – (list of list of tuples) a list of triangles, each being defined by an ordered triplet of 3-tuple points coordinates.

  • materials – (list of tuple) a list of materials defining optical properties of triangles A material is a 1-, 2- or 4-tuple depending on its optical behavior. A 1-tuple encode an opaque material characterised by its reflectance A 2-tuple encode a symmetric translucent material defined by a reflectance and a transmittance A 4-tuple encode an asymmetric translucent material defined the reflectance and transmittance of the upper and lower side respectively

  • lights – (list of tuples) a list of (Energy, (vx, vy, vz)) tuples defining ligh sources By default a normalised zenital light is used. Energy is ligth flux passing throuh a unit area (scene unit) horizontal plane.

  • screen_size – (int) buffer size for projection images (pixels)

  • sensors – (list of list of tuples) a list of triangles defining virtual sensors

Returns:

property) properties computed:

  • index(int) : the indices of the input triangles present in outputs ?

  • label(str) : the internal barcode (canlabel) used by caribu (for debuging)

  • area (float): the individual areas of triangles

  • Eabs (float): the surfacic density of energy absorbed by the triangles (absorbed_energy / area)

  • Ei (float): the surfacic density of energy incoming on the triangles

  • Ei_inf (float): the surfacic density of energy incoming on the inferior face of the triangle

  • Ei_sup (float): the surfacic density of energy incoming on the superior face of the triangle

  • sensor (dict): a dict with id, area, surfacic density of incoming direct energy and surfacic density of incoming total energy of sensors, if any

Return type:

(dict of str

openalea.caribu.caribu.raycasting(triangles, materials, lights=((1, (0, 0, -1)),), domain=None, screen_size=1536, sensors=None, debug=False, canfile=None, optfile=None)[source]#

Compute monochrome illumination of triangles using caribu raycasting mode.

Parameters:

  • triangles – (list of list of tuples) a list of triangles, each being defined by an ordered triplet of 3-tuple points coordinates.

  • materials – (list of tuple) a list of materials defining optical properties of triangles A material is a 1-, 2- or 4-tuple depending on its optical behavior. A 1-tuple encode the reflectance of an opaque material A 2-tuple encode the reflectance and transmittance of a symmetric translucent material A 4-tuple encode the reflectance and transmittance of the upper and lower side of an asymmetric translucent material

  • lights – (list of tuples) a list of (Energy, (vx, vy, vz)) tuples defining ligh sources By default a normalised zenithal light is used. Energy is light flux passing through a unit area (scene unit) horizontal plane.

  • domain – (tuple of floats) 2D Coordinates of the domain bounding the scene for its replication. (xmin, ymin, xmax, ymax) scene is not bounded along z axis if None (default), scene is not repeated

  • screen_size – (int) buffer size for projection images (pixels)

  • sensors – (list of list of tuples) a list of triangles defining virtual sensors

Returns:

property) properties computed:

  • index(int) : the indices of the input triangles present in outputs ?

  • label(str) : the internal barcode (canlabel) used by caribu (for debugging)

  • area (float): the individual areas of triangles

  • Eabs (float): the surfacic density of energy absorbed by the triangles (absorbed_energy / area)

  • Ei (float): the surfacic density of energy incoming on the triangles

  • Ei_inf (float): the surfacic density of energy incoming on the inferior face of the triangle.

  • Ei_sup (float): the surfacic density of energy incoming on the superior face of the triangle

  • sensor (dict): a dict with id, area, surfacic density of incoming direct energy and surfacic density of incoming total energy of sensors, if any

Return type:

(dict of str

openalea.caribu.caribu.sensor_string(triangles)[source]#

format sensor triangles as caribu sensor string content

openalea.caribu.caribu.triangles_string(triangles, labels)[source]#

format triangles and associated labels as caribu canopy string content

openalea.caribu.caribu.write_scene(triangles, materials, canfile, optfile)[source]#
openalea.caribu.caribu.x_mixed_radiosity(triangles, materials, lights, domain, soil_reflectance, diameter, layers, height, sensors=None, screen_size=1536, debug=False)[source]#

Compute multi-chromatic illumination of triangles using mixed-radiosity model.

Parameters:

  • triangles – (list of list of tuples) a list of triangles, each being defined by an ordered triplet of 3-tuple points coordinates.

  • materials – (dict of list of tuple) a {band_name: [materials]} dict defining optical properties of triangles for different band/wavelength A material is a 1-, 2- or 4-tuple depending on its optical behavior. A 1-tuple encode an opaque material characterised by its reflectance A 2-tuple encode a symmetric translucent material defined by a reflectance and a transmittance A 4-tuple encode an asymmetric translucent material defined the reflectance and transmittance of the upper and lower side respectively

  • lights – (list of tuples) a list of (Energy, (vx, vy, vz)) tuples defining light sources Energy is light flux passing through a unit area (scene unit) horizontal plane.

  • domain – (tuple of floats) 2D Coordinates of the domain bounding the scene for its replication. (xmin, ymin, xmax, ymax) scene is not bounded along z axis

  • soil_reflectance – (dict of float) a {band_name: reflectance} dict for the reflectances of the soil

  • diameter – diameter (scene unit) of the sphere defining the close neighbourhood for local radiosity.

  • layers – vertical subdivisions of scene used for approximation of far contribution

  • height – upper limit of canopy layers (scene unit)

  • screen_size – (int) buffer size for projection images (pixels)

  • sensors – (list of list of tuples) a list of triangles defining virtual sensors

Returns:

{property_name:property_values} } dict of dict) with properties:

  • index(int) : the indices of the input triangles present in outputs ?

  • label(str) : the internal barcode (canlabel) used by caribu (for debugging)

  • area (float): the individual areas of triangles

  • Eabs (float): the surfacic density of energy absorbed by the triangles (absorbed_energy / area)

  • Ei (float): the surfacic density of energy incoming on the triangles

  • Ei_inf (float): the surfacic density of energy incoming on the inferior face of the triangle

  • Ei_sup (float): the surfacic density of energy incoming on the superior face of the triangle

  • sensor (dict): a dict with id, area, surfacic density of incoming direct energy and surfacic density of incoming total energy of sensors, if any

Return type:

a ({band_name

openalea.caribu.caribu.x_opt_strings_and_labels(x_materials, x_soil_reflectance)[source]#

format multispectral materials as caribu opt file strings content

openalea.caribu.caribu.x_radiosity(triangles, x_materials, lights=((1, (0, 0, -1)),), screen_size=1536, sensors=None, debug=False)[source]#

Compute multi-chromatic illumination of triangles using radiosity method.

Parameters:

  • triangles – (list of list of tuples) a list of triangles, each being defined by an ordered triplet of 3-tuple points coordinates.

  • x_materials – (dict of list of tuple) a {band_name: [materials]} dict defining optical properties of triangles for different band/wavelength A material is a 1-, 2- or 4-tuple depending on its optical behavior. A 1-tuple encode an opaque material characterised by its reflectance A 2-tuple encode a symmetric translucent material defined by a reflectance and a transmittance A 4-tuple encode an asymmetric translucent material defined the reflectance and transmittance of the upper and lower side respectively

  • lights – (list of tuples) a list of (Energy, (vx, vy, vz)) tuples defining ligh sources By default a normalised zenital light is used. Energy is ligth flux passing throuh a unit area (scene unit) horizontal plane.

  • screen_size – (int) buffer size for projection images (pixels)

  • sensors – (list of list of tuples) a list of triangles defining virtual sensors

Returns:

{property_name:property_values} } dict of dict) with properties:

  • index(int) : the indices of the input triangles present in outputs ?

  • label(str) : the internal barcode (canlabel) used by caribu (for debuging)

  • area (float): the individual areas of triangles

  • Eabs (float): the surfacic density of energy absorbed by the triangles (absorbed_energy / area)

  • Ei (float): the surfacic density of energy incoming on the triangles

  • Ei_inf (float): the surfacic density of energy incoming on the inferior face of the triangle

  • Ei_sup (float): the surfacic density of energy incoming on the superior face of the triangle

  • sensor (dict): a dict with id, area, surfacic density of incoming direct energy and surfacic density of incoming total energy of sensors, if any

Return type:

a {band_name

openalea.caribu.caribu.x_raycasting(triangles, x_materials, lights=((1, (0, 0, -1)),), domain=None, screen_size=1536, sensors=None, debug=False, canfile=None, optfile=None)[source]#

Compute monochrome illumination of triangles using caribu raycasting mode.

Parameters:

  • triangles – (list of list of tuples) a list of triangles, each being defined by an ordered triplet of 3-tuple points coordinates.

  • x_materials – (dict of list of tuple) a {band_name: [materials]} dict defining optical properties of triangles for different band/wavelength A material is a 1-, 2- or 4-tuple depending on its optical behavior. A 1-tuple encode an opaque material characterised by its reflectance A 2-tuple encode a symmetric translucent material defined by a reflectance and a transmittance A 4-tuple encode an asymmetric translucent material defined the reflectance and transmittance of the upper and lower side respectively

  • lights – (list of tuples) a list of (Energy, (vx, vy, vz)) tuples defining ligh sources By default a normalised zenithal light is used. Energy is light flux passing through a unit area (scene unit) horizontal plane.

  • domain – (tuple of floats) 2D Coordinates of the domain bounding the scene for its replication. (xmin, ymin, xmax, ymax) scene is not bounded along z axis if None (default), scene is not repeated

  • screen_size – (int) buffer size for projection images (pixels)

  • sensors – (list of list of tuples) a list of triangles defining virtual sensors

Returns:

{property_name:property_values} } dict of dict) with properties:

  • index(int) : the indices of the input triangles present in outputs ?

  • label(str) : the internal barcode (canlabel) used by caribu (for debuging)

  • area (float): the individual areas of triangles

  • Eabs (float): the surfacic density of energy absorbed by the triangles (absorbed_energy / area)

  • Ei (float): the surfacic density of energy incoming on the triangles

  • Ei_inf (float): the surfacic density of energy incoming on the inferior face of the triangle

  • Ei_sup (float): the surfacic density of energy incoming on the superior face of the triangle

  • sensor (dict): a dict with id, area, surfacic density of incoming direct energy and surfacic density of incoming total energy of sensors, if any

Return type:

a ({band_name

openalea.caribu.CaribuScene module#

This module defines CaribuScene and CaribuSceneError classes.

class openalea.caribu.CaribuScene.CaribuScene(scene=None, light=None, pattern=None, opt=None, soil_reflectance=None, soil_mesh=None, z_soil=None, scene_unit='m', debug=False, filecache=True)[source]#

Bases: object

A class interface to Caribu algorithms

as_primitive()[source]#

Transform scene and materials into simpler python objects

Returns:

auto_screen(screen_resolution)[source]#
bbox()[source]#

Scene bounding box opposite corner points

Returns:

(xmin, ymin, zmin), (xmax, ymax, zmax)

Return type:

two tuples

default_band = 'default_band'#
default_light = (1, (0, 0, -1))#
default_material = (0.06, 0.07)#
default_soil_reflectance = 0.15#
getIncidentEnergy()[source]#

Compute energy of emission of light sources.

Qi is the total horizontal irradiance emitted by sources (m-2) Qem is the sum of the normal-to-the-sources irradiance emitted by sources (m-2) Einc is the total incident energy received on the domain

getSoilEnergy()[source]#

Compute energy received on soil.

plot(a_property=None, minval=None, maxval=None, gamma=None, display=True)[source]#
Parameters:

  • a_property – {dict of float or dict of list of float} : a dict of values, each key being a scene primitive index.

  • minval – (float) minimal value at lower bound of color range if None (default), minimal value of property is used

  • maxval – (float) maximal value at upper bound of color range if None (default), maximal value of property is used

  • gamma (float) – exponent of the normalised values if None (default), na gamma transform is applied

  • display – (bool) : should the scene be displayed ? (default True)

Returns:

A plantGL scene

run(direct=True, infinite=False, d_sphere=0.5, layers=10, height=None, screen_size=1536, screen_resolution=None, sensors=None, split_face=False, simplify=False)[source]#

Compute illumination using the appropriate caribu algorithm

Parameters:

  • direct – (bool) Whether only first order interception is to be computed Default is True (no rediffusions)

  • infinite – (bool) Whether the scene should be considered as infinite Default is False (non-infinite canopy)

  • d_sphere –

    (float) the diameter (m) of the sphere defining the close neighbourhood of mixed radiosity algorithm

    if d_sphere = 0, direct + pure layer algorithm is used

  • layers – (int) the number of horizontal layers for estimating far contributions

  • height – (float) the height of the canopy (m). if None (default), the maximal height of the scene is used.

  • screen_size – (int) size of the screen_size x screen_size square projection screen (pixels)

  • screen_resolution – (float) real world size (meter) of a pixel of the projection screen. If None(default), screen_size is used.

  • sensors – (dict of list of list of tuples) a {sensor_id: [triangle,…]} dict defining the virtual sensors each triangle is a list of tuple defining the coordinates of its vertices

  • split_face – (bool) Whether results of incidence on individual faces

  • False (of triangle should be output. Default is)

  • simplify – (bool) Whether results per band should be simplified to

  • {result_name (a) – property} dict in the case of a monochromatic simulation

Returns:

{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:

  • raw (dict of dict) a {band_name

runPeriodise()[source]#

Call periodise and modify position of triangle in the scene to fit inside pattern

setLight(light)[source]#
triangle_areas(convert=True)[source]#

compute mean area of elementary triangles in the scene

If convert is true, area is expressed in meter (scene unit otherwise)

units = {'cm': 0.01, 'dam': 10, 'dm': 0.1, 'hm': 100, 'km': 1000, 'm': 1, 'mm': 0.001}#
openalea.caribu.CaribuScene.domain_mesh(domain, z=0.0, subdiv=1)[source]#

Create a triangle mesh covering a domain at height z

Parameters:

  • domain – (tuple of float) : a (xmin, ymin, xmax, ymax) tuple defining the extend of a square domain

  • z – the altitude of the mesh

  • subdiv – the number of subdivision of the mesh (not functional)

Returns:

a list of triangles. A triangle is a list of 3-tuples points coordinates

openalea.caribu.CaribuScene.is_mtg_like(obj)[source]#

openalea.caribu.plantgl_adaptor module#

Adaptor for PlantGL object and derived

openalea.caribu.plantgl_adaptor.mtg_to_cscene(g, property_name='geometry')[source]#

Build a caribu-compatible scene from a mtg encoding geometries

Parameters:

  • g – an openalea.mtg.mtg.MTG instance

  • property_name – (str) the name of the property in g where plantGL geometries are encoded

Returns:

[triangles,]} dict.A triangle is a 3-tuple of 3-tuples points coordinates primitive_id is the vertex id.

Return type:

a {primitive_id

openalea.caribu.plantgl_adaptor.pgl_to_triangles(pgl_object, tesselator=None)[source]#
openalea.caribu.plantgl_adaptor.scene_to_cscene(scene)[source]#

Build a caribu-compatible scene from a PlantGl scene

Parameters:

scene – an openalea.plantgl.all.Scene instance

Returns:

[triangles,]} dict.A triangle is a 3-tuple of 3-tuples points coordinates primitive_id is taken as the index of the shape in the scene shape list.

Return type:

a {primitive_id