eradiate.scenes.biosphere.LeafCloud

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

A container class for leaf clouds in abstract discrete canopies. Holds parameters completely characterizing 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') – Identifier of the current scene element.

  • 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) – Identifier of the current scene element.

  • 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 [Ross and Marshak, 1991].

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.

See also

ConeLeafCloudParams

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 [Ross and Marshak, 1991].

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.

See also

CuboidLeafCloudParams

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 [Ross and Marshak, 1991].

An additional parameter controls the random number generator.

Parameters:
Returns:

LeafCloud – Generated leaf cloud.

See also

CylinderLeafCloudParams

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 [Ross and Marshak, 1991].

An additional parameter controls the random number generator.

Parameters:
Returns:

LeafCloud – Generated leaf cloud.

See also

EllipsoidLeafCloudParams

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.

n_leaves()[source]#
Returns:

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 [Ross and Marshak, 1991].

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.

See also

SphereLeafCloudParams

surface_area()[source]#
Returns:

quantity – Total surface area.

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.

traverse(callback)#

Traverse this scene element and collect kernel dictionary template and parameter update map contributions.

Parameters:

callback (SceneTraversal) – Callback data structure storing the collected data.

update()#

Enforce internal state consistency. This method should be called when fields are modified. It is automatically called as a post-init step.

property objects#

Map of child objects associated with this scene element.

Returns:

dict – A dictionary mapping object names to a corresponding object to be inserted in the Eradiate scene graph.

property params#
Returns:

dict[str, UpdateParameter] or None – A dictionary mapping parameter paths, consisting of dot-separated strings, to a corresponding update protocol.

See also

UpdateParameter, UpdateMapTemplate

property template#

Kernel dictionary template contents associated with this scene element.

Returns:

dict – A flat dictionary mapping dot-separated strings describing the path of an item in the nested scene dictionary to values. Values may be objects which can be directly used by the mitsuba.load_dict() function, or InitParameter instances which must be rendered.

See also

InitParameter, KernelDictTemplate

Contents