eradiate.scenes.biosphere.LeafCloud#

class eradiate.scenes.biosphere.LeafCloud(id='leaf_cloud', leaf_positions=NOTHING, leaf_orientations=NOTHING, leaf_radii=NOTHING, leaf_reflectance=0.5, leaf_transmittance=0.5)[source]#

Bases: eradiate.scenes.biosphere._core.CanopyElement

A container class for leaf clouds in abstract discrete canopies. Holds parameters completely characterising the leaf cloud’s leaves.

In practice, this class should rarely be instantiated directly using its constructor. Instead, several class method constructors are available:

Class method constructors

cuboid([seed, avoid_overlap])

Generate a leaf cloud with an axis-aligned cuboid shape (and a square footprint on the ground).

cylinder([seed])

Generate a leaf cloud with a cylindrical shape (vertical orientation).

ellipsoid([seed])

Generate a leaf cloud with ellipsoid shape.

from_file(filename[, leaf_transmittance, ...])

Construct a LeafCloud from a text file specifying the leaf positions and orientations.

sphere([seed])

Generate a leaf cloud with spherical shape.

Parameters
  • id (str, optional, default: 'leaf_cloud') – User-defined object identifier.

  • leaf_positions (array-like, default: []) – Leaf positions in cartesian coordinates as a (n, 3)-array.

    Unit-enabled field (default: ucc[‘length’]).

  • leaf_orientations (ndarray, default: []) – Leaf orientations (normal vectors) in Cartesian coordinates as a (n, 3)-array.

  • leaf_radii (array-like, default: []) – Leaf radii as a n-array.

    Unit-enabled field (default: ucc[length]).

  • leaf_reflectance (Spectrum or dict, default: 0.5) – Reflectance spectrum of the leaves in the cloud. Must be a reflectance spectrum (dimensionless).

  • leaf_transmittance (Spectrum or dict, default: 0.5) – Transmittance spectrum of the leaves in the cloud. Must be a transmittance spectrum (dimensionless).

Fields
  • id (str or None) – User-defined object identifier.

  • leaf_positions (quantity) – Leaf positions in cartesian coordinates as a (n, 3)-array.

  • leaf_orientations (ndarray) – Leaf orientations (normal vectors) in Cartesian coordinates as a (n, 3)-array.

  • leaf_radii (quantity) – Leaf radii as a n-array.

  • leaf_reflectance (Spectrum) – Reflectance spectrum of the leaves in the cloud.

  • leaf_transmittance (Spectrum) – Transmittance spectrum of the leaves in the cloud.

classmethod cone(seed=12345, **kwargs)[source]#

Generate a leaf cloud with a right conical shape (vertical orientation). Parameters are checked by the ConeLeafCloudParams class.

The produced leaf cloud covers uniformly the \(r < \mathtt{radius} \cdot \left( 1 - \frac{z}{l_v} \right), z \in [0, l_v]\) region. Leaf orientation is controlled by the mu and nu parameters of an approximated inverse beta distribution [RM91].

An additional parameter controls the random number generator.

Parameters
  • seed (int) – Seed for the random number generator.

  • **kwargs – Keyword arguments interpreted by ConeLeafCloudParams.

Returns

LeafCloud – Generated leaf cloud.

classmethod cuboid(seed=12345, avoid_overlap=False, **kwargs)[source]#

Generate a leaf cloud with an axis-aligned cuboid shape (and a square footprint on the ground). Parameters are checked by the CuboidLeafCloudParams class, which allows for many parameter combinations.

The produced leaf cloud uniformly covers the \((x, y, z) \in \left[ -\dfrac{l_h}{2}, + \dfrac{l_h}{2} \right] \times \left[ -\dfrac{l_h}{2}, + \dfrac{l_h}{2} \right] \times [0, l_v]\) region. Leaf orientation is controlled by the mu and nu parameters of an approximated inverse beta distribution [RM91].

Finally, extra parameters control the random number generator and a basic and conservative leaf collision detection algorithm.

Parameters
  • seed (int) – Seed for the random number generator.

  • avoid_overlap (bool) – If True, generate leaf positions with strict collision checks to avoid overlapping.

  • n_attempts (int) – If avoid_overlap is True, number of attempts made at placing a leaf without collision before giving up. Default: 1e5.

  • **kwargs – Keyword arguments interpreted by CuboidLeafCloudParams.

Returns

LeafCloud – Generated leaf cloud.

classmethod cylinder(seed=12345, **kwargs)[source]#

Generate a leaf cloud with a cylindrical shape (vertical orientation). Parameters are checked by the CylinderLeafCloudParams class.

The produced leaf cloud covers uniformly the \(r < \mathtt{radius}, z \in [0, l_v]\) region. Leaf orientation is controlled by the mu and nu parameters of an approximated inverse beta distribution [RM91].

An additional parameter controls the random number generator.

Parameters
Returns

LeafCloud – Generated leaf cloud.

classmethod ellipsoid(seed=12345, **kwargs)[source]#

Generate a leaf cloud with ellipsoid shape. Parameters are checked by the EllipsoidLeafCloudParams class.

The produced leaf cloud covers uniformly the volume enclosed by \(\frac{x^2}{a^2} + \frac{y^2}{b^2} + \frac{z^2}{c^2}= 1\) .

Leaf orientation is controlled by the mu and nu parameters of an approximated inverse beta distribution [RM91].

An additional parameter controls the random number generator.

Parameters
Returns

LeafCloud – Generated leaf cloud.

classmethod from_file(filename, leaf_transmittance=0.5, leaf_reflectance=0.5, id='leaf_cloud')[source]#

Construct a LeafCloud from a text file specifying the leaf positions and orientations.

File format

Each line defines a single leaf with the following 7 numerical parameters separated by one or more spaces:

  • leaf radius;

  • leaf center (x, y and z coordinates);

  • leaf orientation (x, y and z of normal vector).

Important

All quantities are assumed to be given in metre.

Parameters
  • filename (path-like) – Path to the text file specifying the leaves in the leaf cloud. Can be absolute or relative.

  • leaf_reflectance (Spectrum or float) – Reflectance spectrum of the leaves in the cloud. Must be a reflectance spectrum (dimensionless). Default: 0.5.

  • leaf_transmittance (Spectrum of float) – Transmittance spectrum of the leaves in the cloud. Must be a transmittance spectrum (dimensionless). Default: 0.5.

  • id (str) – ID of the created LeafCloud instance.

Returns

LeafCloud – Generated leaf cloud.

Raises

FileNotFoundError – If filename does not point to an existing file.

kernel_bsdfs(ctx)[source]#

Return BSDF plugin specifications.

Parameters

ctx (KernelDictContext) – A context data structure containing parameters relevant for kernel dictionary generation.

Returns

dict – Return a dictionary suitable for merge with a KernelDict containing all the BSDFs attached to the shapes in the leaf cloud.

kernel_dict(ctx)#

Return a dictionary suitable for kernel scene configuration.

Parameters

ctx (KernelDictContext) – A context data structure containing parameters relevant for kernel dictionary generation.

Returns

KernelDict – Kernel dictionary which can be loaded as a Mitsuba object.

kernel_shapes(ctx)[source]#

Return shape plugin specifications.

Parameters

ctx (KernelDictContext) – A context data structure containing parameters relevant for kernel dictionary generation.

Returns

dict – A dictionary suitable for merge with a KernelDict containing all the shapes in the leaf cloud.

n_leaves()[source]#

int : Number of leaves in the leaf cloud.

classmethod sphere(seed=12345, **kwargs)[source]#

Generate a leaf cloud with spherical shape. Parameters are checked by the SphereLeafCloudParams class.

The produced leaf cloud covers uniformly the \(r < \mathtt{radius}\) region. Leaf orientation is controlled by the mu and nu parameters of an approximated inverse beta distribution [RM91].

An additional parameter controls the random number generator.

Parameters
  • seed (int) – Seed for the random number generator.

  • **kwargs – Keyword arguments interpreted by SphereLeafCloudParams.

Returns

LeafCloud – Generated leaf cloud.

surface_area()[source]#

quantity : Total surface area as a Quantity.

translated(xyz)[source]#

Return a copy of self translated by the vector xyz.

Parameters

xyz (pint.Quantity) – A 3-vector or a (N, 3)-array by which leaves will be translated. If (N, 3) variant is used, the array shape must match that of leaf_positions.

Returns

LeafCloud – Translated copy of self.

Raises

ValueError – Sizes of xyz and self.leaf_positions are incompatible.