eradiate.scenes.biosphere.DiscreteCanopy#

class eradiate.scenes.biosphere.DiscreteCanopy(id='canopy', size=None, instanced_canopy_elements=NOTHING)[source]#

Bases: eradiate.scenes.biosphere._core.Canopy

Discrete canopy scene element [discrete_canopy].

A discrete canopy composed of one or several CanopyElement instances. The underlying implementation holds a list of InstancedCanopyElement, allowing for arbitrary cloning of each CanopyElement. The produced canopy can be padded with clones of itself using the padded_copy() method.

Class method constructors

homogeneous([padding, id])

Generate a homogeneous discrete canopy, possibly padded with copies of itself.

leaf_cloud_from_files(size, leaf_cloud_dicts)

Directly create a leaf cloud canopy from text file specifications, possibly padded with copies of itself.

padded([padding])

Create a discrete canopy and pad it with copies of itself.

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

  • size (array-like) – Canopy size as a 3-vector.

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

  • instanced_canopy_elements (list of InstancedCanopyElement, default: []) – List of CanopyElement defining the canopy. Can be initialised with a InstancedCanopyElement, which will be automatically wrapped into a list. Dictionary-based specifications are allowed as well.

Fields
classmethod homogeneous(padding=0, id='homogeneous_discrete_canopy', **leaf_cloud_kwargs)[source]#

Generate a homogeneous discrete canopy, possibly padded with copies of itself.

Parameters
  • padding (int) – Amount of padding around the canopy. Must be positive or zero. The resulting padded canopy is a grid of \(2 \times \mathit{padding} + 1\) copies.

  • id (str, default: "homogeneous_discrete_canopy") – Canopy object ID.

  • **leaf_cloud_kwargs – Keyword arguments forwarded to LeafCloud.cuboid().

Returns

DiscreteCanopy – Created canopy object.

Notes

The leaf cloud’s ID will be set to f"{id}_leaf_cloud".

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 canopy.

kernel_dict(ctx)[source]#

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_instances(ctx)[source]#

Return instance plugin specifications.

Returns

dict – A dictionary suitable for merge with a KernelDict containing instances.

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 canopy.

classmethod leaf_cloud_from_files(size, leaf_cloud_dicts, padding=0, id='discrete_canopy')[source]#

Directly create a leaf cloud canopy from text file specifications, possibly padded with copies of itself.

CanopyElement dictionary format

Each item of the leaf_cloud_dicts list shall have the following structure:

{
    "sub_id": "some_value",  # leaf cloud ID string part, optional if leaf_cloud_dicts has only 1 entry
    "instance_filename": "some_path",  # path to instance specification file
    "leaf_cloud_filename": "some_other_path", # path to leaf cloud specification file
    "leaf_reflectance": 0.5,  # optional, leaf reflectance (default: 0.5)
    "leaf_transmittance": 0.5,  # optional, leaf transmittance (default: 0.5)
}
Parameters
  • size (quantity) – Canopy size as a 3-vector (in metres).

  • leaf_cloud_dicts (list of dict) – List of dictionary specifying canopy elements and instances (see format above).

  • padding (int, default: 0) – Amount of padding around the canopy. Must be positive or zero. The resulting padded canopy is a grid of \(2 \times \mathit{padding} + 1\) copies.

  • id (str, default: "discrete_canopy") – Canopy ID.

Returns

DiscreteCanopy – Created canopy object.

classmethod padded(padding=0, **kwargs)[source]#

Create a discrete canopy and pad it with copies of itself. Keyword arguments are forwarded to the default constructor.

Parameters
  • padding (int) – Amount of padding around the canopy. Must be positive or zero. The resulting padded canopy is a grid of \(2 \times \mathit{padding} + 1\) copies.

  • **kwargs`` – Keyword arguments forwarded to the DiscreteCanopy constructor.

Returns

DiscreteCanopy – Padded discrete canopy.

padded_copy(padding)[source]#

Return a copy of the current canopy padded with additional copies.

Parameters

padding (int) – Amount of padding around the canopy. Must be positive or zero. The resulting padded canopy is a grid of \(2 \times \mathit{padding} + 1\) copies.

Returns

DiscreteCanopy – Padded copy of self.