eradiate.scenes.biosphere.LeafCloud
eradiate.scenes.biosphere.LeafCloud#
- class eradiate.scenes.biosphere.LeafCloud(id='leaf_cloud', leaf_positions=_Nothing.NOTHING, leaf_orientations=_Nothing.NOTHING, leaf_radii=_Nothing.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:
generators create leaf clouds from a set of parameters:
LeafCloud.from_file()
loads leaf positions and orientations from a text file.
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
ordict
, default:0.5
) – Reflectance spectrum of the leaves in the cloud. Must be a reflectance spectrum (dimensionless).leaf_transmittance (
Spectrum
ordict
, default:0.5
) – Transmittance spectrum of the leaves in the cloud. Must be a transmittance spectrum (dimensionless).
- Fields
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
andnu
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.
See also
- 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
andnu
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
) – IfTrue
, generate leaf positions with strict collision checks to avoid overlapping.n_attempts (
int
) – Ifavoid_overlap
isTrue
, 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
- 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
andnu
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
CylinderLeafCloudParams
.
- Returns
LeafCloud
– Generated leaf cloud.
See also
- 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
andnu
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
EllipsoidLeafCloudParams
.
- Returns
LeafCloud
– Generated leaf cloud.
See also
- 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
orfloat
) – Reflectance spectrum of the leaves in the cloud. Must be a reflectance spectrum (dimensionless). Default: 0.5.leaf_transmittance (
Spectrum
offloat
) – Transmittance spectrum of the leaves in the cloud. Must be a transmittance spectrum (dimensionless). Default: 0.5.
- 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 aKernelDict
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 aKernelDict
containing all the shapes 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
andnu
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.
See also
- 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 ofleaf_positions
.- Returns
LeafCloud
– Translated copy of self.- Raises
ValueError – Sizes of
xyz
andself.leaf_positions
are incompatible.