hothouse package

Submodules

hothouse.blaster module

class hothouse.blaster.BouncedRayBlaster(*args: t.Any, **kwargs: t.Any)

Bases: RayBlaster

Blaster created by bouncing rays off of a scene.

Parameters:

• hits (dict) – Raytracer results for the provided rays.

• prev_origins (np.ndarray) – Origins of rays before the bounce.

• prev_directions (np.ndarray) – Unit vectors describing ray directions before the bounce.

• prev_ray_intensity (np.ndarray, optional) – Ray intensity before the bounce.

• prev_original_ray_index (np.ndarray, optional) – Index of the original ray in the primary blaster that produced each of the rays prior to the bounce.

• ray_intensity_threshold_rel (float, optional) – Relative threshold below which rays should no longer be tracked.

• ray_intensity_threshold_abs (float, optional) – Absolute threshold below which rays should no longer be tracked.

bounce(hits, **kwargs)

Create a ray tracer for bounced rays.

Parameters:

• hits (dict, optional) – Results from running this ray tracer.

• **kwargs – Additional keyword arguments are passed to BouncedRayBlaster.

Returns:

Blaster containing ray information for the

bounced rays.

Return type:

BouncedRayBlaster

cast_once(scene, verbose_output=True, query_type=QueryType.INTERSECT, dists=None, multibounce=False, include_attributes=['reflectance', 'transmittance'], **kwargs)

Run the embree raytrace once on a scene for this bounce. Note that many of the defaults for this method differ than those for the base RayBlaster due to the way it is intended to be used.

Parameters:

• scene (hothouse.scene.Scene) – Scene to raytrace.

• verbose_output (bool, optional) – If True, output a dictionary of all ray properties.

• query_type (QueryType, optional) – Raytrace query type controlling the output.

• dists (np.ndarray, optional) – Array of distances for each ray that should be updated.

• multibounce (bool, optional) – If True, rays should be tracked through reflections/transmission.

• include_attributes (bool, list) – If True, include all face attributes for each intercepted face in the results. If a list is provided, just the specified attributes will be included. This will be ignored if verbose_output is False.

• **kwargs – Additional keyword arguments are passed to BouncedRayBlaster if multibounce is True.

Returns:

Ray trace result.

Return type:

np.ndarray, dict

directions

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

hits

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

idx_hits

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

idx_reflected

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

idx_transmitted

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

intersections

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

join_bounces(bounces)

Combine output from a set of bounces.

Parameters:

bounces (list) – Output from raytrace for each bounce.

Returns:

Combined data from the bounces.

Return type:

dict

original_ray_index

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

origins

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

prev_directions

A numpy array trait type.

prev_nray

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

prev_original_ray_index

A numpy array trait type.

prev_origins

A numpy array trait type.

prev_ray_intensity

A numpy array trait type.

ray_intensity

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

ray_intensity_threshold_abs

A casting version of the float trait.

ray_intensity_threshold_rel

A casting version of the float trait.

reflected_directions

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

reflected_intensity

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

reflected_origins

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

classmethod resize_bounces(bounces, maxbounce)

Resize bounce output data to match a new number of maximum bounces.

Parameters:

• bounces (dict) – Joined output from raytrace for a set of bounces.

• maxbounce (int) – New number of maximum bounces.

transmitted_directions

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

transmitted_intensity

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

transmitted_origins

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

class hothouse.blaster.OrthographicRayBlaster(*args: t.Any, **kwargs: t.Any)

Bases: RayBlaster

Container for orthographic set of rays in a square.

Parameters:

• center (np.ndarray) – Center of the set of rays.

• forward (np.ndarray) – Unit vector giving the ray direction.

• up (np.ndarray, optional) – Unit vector giving the y direction of the ray pattern. Required if east not provided.

• east (np.ndarray, optional) – Unit vector giving the x direction of the ray pattern. Required if up not provided.

• width (float, optional) – Width of the ray pattern.

• height (float, optional) – Height of the ray pattern.

• nx (int, optional) – Number of rays distributed in the x (east) direction.

• ny (int, optional) – Number of rays distributed in the y (up) direction.

• period (np.ndarray, optional) – Number of times the rays should be repeated in the up & east directions.

• intensity (float, optional) – Total intensity of light in rays.

• intensity_density (float, optional) – Intensity of light in rays per unit area. If provided and intensity is not, this will be used to calculate intensity.

• **kwargs – Additional keyword arguments are passed to RayBlaster.

cast_once(scene, verbose_output=False, query_type=QueryType.DISTANCE, dists=None, **kwargs)

Run the embree raytrace once on a scene.

Parameters:

• scene (hothouse.scene.Scene) – Scene to raytrace.

• verbose_output (bool, optional) – If True, output a dictionary of all ray properties.

• query_type (QueryType, optional) – Raytrace query type controlling the output.

• dists (np.ndarray, optional) – Array of distances for each ray that should be updated.

• **kwargs – Additional keyword arguments are passed to the RayBlaster method.

Returns:

Ray trace result.

Return type:

np.ndarray, dict

center

A numpy array trait type.

east

A numpy array trait type.

forward

A numpy array trait type.

height

A casting version of the float trait.

intensity

A casting version of the float trait.

intensity_density

A casting version of the float trait.

is_periodic

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

nx

A casting version of the int trait.

ny

A casting version of the int trait.

period

A numpy array trait type.

up

A numpy array trait type.

width

A casting version of the float trait.

class hothouse.blaster.ProjectionRayBlaster(*args: t.Any, **kwargs: t.Any)

Bases: RayBlaster

Container for a set of rays projected from a camera image plane.

Parameters:

• fov_width (float) – Field of view width (in degrees).

• fov_height (float) – Field of view height (in degrees).

• center (np.ndarray) – Center of the set of rays.

• forward (np.ndarray) – Unit vector giving the ray direction at the center of the field of view.

• up (np.ndarray, optional) – Unit vector giving the y direction of the ray pattern. Required if east not provided.

• east (np.ndarray, optional) – Unit vector giving the x direction of the ray pattern. Required if up not provided.

• width (float, optional) – Width of the ray pattern.

• height (float, optional) – Height of the ray pattern.

• nx (int, optional) – Number of rays distributed in the x (east) direction.

• ny (int, optional) – Number of rays distributed in the y (up) direction.

camera_distance

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

camera_origin

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

center

A numpy array trait type.

east

A numpy array trait type.

forward

A numpy array trait type.

fov_height

A casting version of the float trait.

fov_width

A casting version of the float trait.

height

A casting version of the float trait.

nx

A casting version of the int trait.

ny

A casting version of the int trait.

up

A numpy array trait type.

width

A casting version of the float trait.

class hothouse.blaster.QueryType(*values)

Bases: Enum

Identifier for query that should be run.

DISTANCE = 'DISTANCE'

INTERSECT = 'INTERSECT'

OCCLUDED = 'OCCLUDED'

class hothouse.blaster.RayBlaster(*args: t.Any, **kwargs: t.Any)

Bases: HasTraits

Container for a set of rays.

Parameters:

• origins (np.ndarray) – Ray origins.

• directions (np.ndarray) – Unit vectors describing ray directions.

• ray_intensity (np.ndarray, optional) – Intensity of light in each ray.

• intensity (float, optional) – Total intensity of light in rays.

• diffuse_intensity (float, optional) – Diffuse intensity.

bounce(hits, **kwargs)

Create a ray tracer for bounced rays.

Parameters:

• hits (dict, optional) – Results from running this ray tracer.

• **kwargs – Additional keyword arguments are passed to BouncedRayBlaster.

Returns:

Blaster containing ray information for the

bounced rays.

Return type:

BouncedRayBlaster

cast_once(scene, verbose_output=False, query_type=QueryType.DISTANCE, dists=None, multibounce=False, include_attributes=False, **kwargs)

Run the embree raytrace once on a scene.

Parameters:

• scene (hothouse.scene.Scene) – Scene to raytrace.

• verbose_output (bool, optional) – If True, output a dictionary of all ray properties.

• query_type (QueryType, optional) – Raytrace query type controlling the output.

• dists (np.ndarray, optional) – Array of distances for each ray that should be updated.

• multibounce (bool, optional) – If True, rays should be tracked through reflections/transmission.

• include_attributes (bool, list) – If True, include all face attributes for each intercepted face in the results. If a list is provided, just the specified attributes will be included. This will be ignored if verbose_output is False.

• **kwargs – Additional keyword arguments are passed to BouncedRayBlaster if multibounce is True.

Returns:

Ray trace result.

Return type:

np.ndarray, dict

compute_count(scene, **kwargs)

Run the raytracer to determine how each ray will intersect the scene.

Parameters:

• scene (hothouse.scene.Scene) – Scene to cast rays on.

• **kwargs – Additional keyword arguments are passed to cast_once.

Returns:

Raytrace results:

geomID (np.ndarray): Index of the scene component that
    each ray intersects. -1 for no intersection.
primID (np.ndarray): Index of the component face that
    each ray intersects within the component geometry
    that contains it. -1 for no intersection.
tfar (np.ndarray): The distance that each ray traveled
    before intersecting a surface in the scene.
Ng (np.ndarray): Normal vector for the surface that each
    ray intersected.
u (np.ndarray): Projection of the ray up along the
    surface that each ray intersected
    (barycentric u coordinate of hit).
v (np.ndarray): Projection of the ray east along the
    surface that each ray intersected
    (barycentric v coordinate of hit).
ray_dir (np.ndarray): Unit vectors for the rays. (Only
    included by BouncedRayBlaster).
ray_intensity (np.ndarray): Intensity of each ray. (Only
    included by BouncedRayBlaster).
original_ray_index (np.ndarray): Index of the original
    ray that spawned each of the rays in this blaster.
    (Only included by BouncedRayBlaster).
bounces (dict): Raytrace results for bounces if
    multibounce keyword argument is True.

Return type:

dict

compute_distance(scene)

Get the distance that each ray will travel before hitting a surface in the scene.

Parameters:

scene (hothouse.scene.Scene) – Scene to cast rays on.

Returns:

Travel distances for each ray.

Return type:

np.ndarray

compute_flux_density(scene, light_sources, **kwargs)

Compute the flux density on each scene element touched by this blaster from a set of light sources.

Parameters:

• scene (hothouse.scene.Scene) – Scene to get flux density for.

• light_sources (list) – Set of RayBlasters used to determine the light incident on scene elements.

• **kwargs – Additional keyword arguments are passed to scene.compute_flux_density.

Returns:

Total flux density on surfaces intercepted by the

rays.

Return type:

array

compute_intersect(scene)

Get the indices of intersected faces that the rays intersect.

Parameters:

scene (hothouse.scene.Scene) – Scene to cast rays on.

Returns:

Indices of faces that are intersected. -1

indicates no intersection.

Return type:

np.ndarray

compute_occluded(scene)

Get a mask for rays that will be occluded.

Parameters:

scene (hothouse.scene.Scene) – Scene to cast rays on.

Returns:

Mask for occluded rays, where 0 indicates an

occluded ray and -1 indicated unoccluded.

Return type:

np.ndarray

diffuse_intensity

A casting version of the float trait.

directions

A numpy array trait type.

intensity

A casting version of the float trait.

property nray

Number of rays in the blaster.

Type:

int

origins

A numpy array trait type.

ray_intensity

A numpy array trait type.

class hothouse.blaster.SphericalRayBlaster(*args: t.Any, **kwargs: t.Any)

Bases: ProjectionRayBlaster

Container for a set of spherically distributed rays.

Parameters:

• fov_width (float) – Field of view width (in degrees). This will be the angle of rotation of the rays around the forward direction.

• fov_height (float) – Field of view height (in degrees). This will be the angle of rotation of rays away from the forward direction.

• center (np.ndarray) – Center of the set of rays.

• forward (np.ndarray) – Unit vector giving the ray direction at the center of the field of view.

• dont_include_center (bool, optional) – If True, don't include an explicit ray along the forward vector. If False, the center ray will be the first ray.

camera_distance = None

camera_origin = None

dont_include_center

A casting version of the boolean trait.

fov_height

A casting version of the float trait.

fov_width

A casting version of the float trait.

height = None

width = None

class hothouse.blaster.SunRayBlaster(*args: t.Any, **kwargs: t.Any)

Bases: OrthographicRayBlaster

Container for an orthographic set of rays with properties set based on the position of the sun for a given location and date/time.

Parameters:

• latitude (float) – Location latitude (in degrees).

• longitude (float) – Location longitude (in degrees).

• date (datetime.datetime) – Date/time.

• ground (np.ndarray) – Position of the center of the ray projection on the ground.

• zenith (np.ndarray) – Position directly above ‘ground’ at distance that sun blaster should be placed.

• north (np.ndarray) – Direction of north on ground from ‘ground’.

• solar_altitude (float) – Angle of sun above the horizon.

• solar_azimuth (float) – Angle of sun around the horizon from north.

• solar_distance (float) – Distance of sun from ground.

• scene_limits (np.ndarray) – Set of points defining the bounds of the scene.

• altitude (float, optional) – Altitude (in meters) used to compute solar position. If not provided, but pressure is, pressure will be used to calculate altitude.

• pressure (float, optional) – Pressure (in Pa) used to compute solar position. If not provided, but altitude is, altitude will be used to calculate pressure.

• temperature (float, optional) – Air temperature (in degrees C) used to compute solar position.

• eta_par (float, optional) – Fraction of solar radiation (assuming black-body spectrum of 5800 K) that is photosynthetically active (wavelengths 400–700 nm).

• eta_photon (float, optional) – Average number of photons per photosynthetically activate unit of radiation (in µmol s−1 W−1).

altitude

A float trait.

date

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

eta_par

A float trait.

eta_photon

A float trait.

classmethod get_solar_direction(latitude, longitude, date, up, north, **kwargs)

Get the direction that rays from the sun will travel for a given location, time, and orientation.

Parameters:

• latitude (float) – Location latitude (in degrees).

• longitude (float) – Location longitude (in degrees).

• date (datetime.datetime) – Date/time.

• up (np.ndarray, optional) – Normal unit vector for the ground.

• north (np.ndarray) – Unit vector for the north cardinal direction.

• **kwargs – Additional keyword arguments are passed to SunRayBlaster instance.

Returns:

Unit vector in the direction of sun rays.

Return type:

np.ndarray

ground

A numpy array trait type.

latitude

A float trait.

limits_east

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

limits_up

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

longitude

A float trait.

north

A numpy array trait type.

pressure

A float trait.

scene_limits

A numpy array trait type.

solar_altitude

A casting version of the float trait.

solar_azimuth

A casting version of the float trait.

solar_distance

A casting version of the float trait.

solar_east

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

solar_ppfd

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

solar_rotation(point, is_ray=False)

Rotate a point according to same rotation that moves sun from the zenith to its location in the sky.

Parameters:

• point (array) – 3D point to rotate

• is_ray (bool, optional) – If True, the point is treated as a ray and will not be shifted prior to rotation.

solpos_info

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

temperature

A float trait.

zenith

A numpy array trait type.

zenith_direction

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

hothouse.callback_handler module

hothouse.cli module

Console script for hothouse.

hothouse.datasets module

hothouse.hothouse module

Main module.

hothouse.model module

class hothouse.model.Model(*args: t.Any, **kwargs: t.Any)

Bases: HasTraits

Container for 3D geometries that can be added to scenes.

Parameters:

• vertices (np.ndarray) – Set of vertices used by the geometry.

• indices (np.ndarray) – Indices of vertices comprising each face in the geometry.

• attributes (np.ndarray, optional) – Attributes of each face in the geometry (e.g. color).

• triangles (np.ndarray, optional) – Positions of vertices that make up each face.

• normals (np.ndarray, optional) – Normal unit vectors for each face.

• vertex_normals (np.ndarray, optional) – Normal unit vectors for each vertex.

areas

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

attributes

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

face_colors

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

classmethod from_file(filename, **kwargs)

Create a model from a 3D mesh loaded from a file.

Parameters:

• filename (str) – Path to file.

• **kwargs – Additional keyword arguments are passed to either from_obj or from_ply after determine the file type from its extension.

Returns:

Model containing the loaded geometry.

Return type:

Model

Raises:

ValueError – If filename has an unsupported extension.

classmethod from_obj(filename, attributes=None, **kwargs)

Create a model from a 3D mesh described by an ObjWavefront file.

Parameters:

• filename (str) – Path to ObjWavefront file.

• attributes (dict, optional) – Mapping of attribute name to an array of values for that attribute at each face.

• **kwargs – Additional keyword arguments are passed to the class constructor.

Returns:

Model containing the loaded geometry.

Return type:

Model

classmethod from_ply(filename, attributes=None, **kwargs)

Create a model from a 3D mesh described by a ply file.

Parameters:

• filename (str) – Path to ply file.

• attributes (dict, optional) – Mapping of attribute name to an array of values for that attribute at each face.

• **kwargs – Additional keyword arguments are passed to the class constructor.

Returns:

Model containing the loaded geometry.

Return type:

Model

property geometry

Model geometry.

Type:

pythreejs.BufferGeometry

indices

A numpy array trait type.

property nface

Number of faces in the model.

Type:

int

normals

A numpy array trait type.

property nvert

Number of vertices in the model.

Type:

int

translate(delta)

Shift the vertices in the model geometry.

Parameters:

delta (np.ndarray) – Shift to apply.

triangles

A numpy array trait type.

triangles_f4

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

vertex_colors

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

vertex_normals

A numpy array trait type.

vertices

A numpy array trait type.

hothouse.model.pairwise(iterable)

s -> (s0,s1), (s1,s2), (s2, s3), …

hothouse.ray_callbacks module

hothouse.scene module

class hothouse.scene.CastAccumulator(*args: t.Any, **kwargs: t.Any)

Bases: HasTraits

Wrapper for function to accumulate ray trace results.

Parameters:

• name (str) – Name of accumulator.

• function (callable, optional) –

  Function method that should be used to accumulate ray trace results. If not provided, the Scene class method with the name f’_accumulate_{name}’ will be used. The function must take the following arguments:

  dst (np.ndarray): Destination array that values
      should be added to.
  component (hothouse.model.Model): Scene component
      that value is being calculated for.
  ray_dir (np.ndarray): Directions of rays.
  ray_intensity (np.ndarray): Intensity of rays.
  primID (np.ndarray): Index of the component face that
      each ray intersects within the component geometry
      that contains it. -1 for no intersection.
  tfar (np.ndarray): The distance that each ray
      traveled before intersecting a surface in the
      scene.
  Ng (np.ndarray): Normal vector for the surface that
      each ray intersected.
  u (np.ndarray): Projection of the ray up along the
      surface that each ray intersected
      (barycentric u coordinate of hit).
  v (np.ndarray): Projection of the ray east along the
      surface that each ray intersected
      (barycentric v coordinate of hit).
  

• dtype (np.dtype, optional) – Data type of the result array that the accumulator expects.

• value (int, float, optional) – Initial value that the result array should be populated with.

• no_multibounce (bool, optional) – If True, don’t accumulate for bounces.

• kws (dict, optional) – Keyword arguments to pass to the accumulator function when it is called via the accumulate method.

accumulate(dst, ci, component, counts, idx=None, idx_bounces=None, **kwargs)

Accumulate raytracer results for a component.

Parameters:

• dst (dict) – Mapping to contain accumulated results.

• ci (int) – Component index.

• component (hothouse.model.Model) – Scene component that value is being calculated for.

• counts (dict) – Raytracer results.

• idx (np.ndarray, optional) – Index of rays that hit the provided component.

• idx_bounces (np.ndarray, optional) – Index of ray bounces that hit the provided component.

• **kwargs – Additional keyword arguments can be used to override or supplement values in counts.

dtype

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

classmethod from_kwargs(name, v)

Create a CastAccumulator instance from user provided keyword arguments.

Parameters:

• name (str) – Accumulator name.

• v (callable, tuple, dict) – Callable accumulator function, tuple containing an accumulator function and a dictionary of keyword arguments that should be passed to the accumulator function, or a dictionary of keyword arguments to pass to the CastAccumulator constructor.

Returns:

Accumulator instance.

Return type:

CastAccumulator

function

A trait which is callable.

Notes

Classes are callable, as are instances with a __call__() method.

kws

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

name

A trait for unicode strings.

no_multibounce

A boolean (True, False) trait.

value

A casting version of the float trait.

class hothouse.scene.PeriodicScene(*args: t.Any, **kwargs: t.Any)

Bases: Scene

Container for a scene in which components are repeated.

Parameters:

• period (np.ndarray, optional) – Period of repetition for components in each direction.

• direction (np.ndarray, optional) – Unit vectors for directions over which components will be repeated.

• count (np.ndarray, optional) – Number of times that components will be repeated in each direction.

• dont_reflect (bool, optional) – If True, the components will only be repeated in the provided directions. If False, the components will be repeated in both the provided directions and the reflections of those directions.

• dont_center (bool, optional) – If False, the periodic components will be added such that the original components remain as close to the center of the scene as possible without modifying their original positions. If True, the periodic components will all be added in the provided directions.

• buffer_as_primary (bool, optional) – If True, hits of periodic components will be treated as the original components during ray tracing.

add_component(component)

Add a component to the scene.

Parameters:

component (hothouse.model.Model) – 3D component.

buffer_as_primary

A boolean (True, False) trait.

count

A numpy array trait type.

direction

A numpy array trait type.

dont_center

A boolean (True, False) trait.

dont_reflect

A boolean (True, False) trait.

classmethod get_periodic_shifts(period, direction, count, dont_reflect=False, dont_center=False)

Get the shifts that should be applied to plants.

Parameters:

• period (np.ndarray) – Length of the period along each direction.

• direction (np.ndarray) – Unit vector for the directions along which the period should be applied.

• count (np.ndarray) – Number of times the period should be repeated in each direction.

• include_origin (bool, optional) – If True, include the origin in the returned shifts.

• dont_reflect (bool, optional) – If True, the shifts will only occur in the positive direction along each axis.

• dont_center (bool, optional) – If True, this shifts will not be centered on the origin.

Returns:

Shifts in each coordinate that should be applied.

Return type:

np.ndarray

property ncomponents_periodic

Total number of periodic components in the scene.

Type:

int

property nperiodic_copies

Number of periodic copies of each component in the scene.

Type:

int

period

A numpy array trait type.

periodic_shifts

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

post_cast(query_type, output)

Finalize the results from running the ray tracer.

Parameters:

• query_type (QueryType) – Raytrace query type of the output.

• output (object) – Raytracer result.

Returns:

Finalized raytracer result.

Return type:

object

class hothouse.scene.Scene(*args: t.Any, **kwargs: t.Any)

Bases: HasTraits

Container for component geometries that will be traced and properties of the context in which they reside.

Parameters:

• ground (np.ndarray, optional) – Scene center.

• up (np.ndarray, optional) – Normal unit vector for the ground.

• north (np.ndarray, optional) – Unit vector for the north cardinal direction.

• components (list, optional) – 3D components in the scene.

• meshes (list, optional) – 3D geometries for the components in the scene.

• embree_scene (pyembree.EmbreeScene, optional)

add_component(component)

Add a component to the scene.

Parameters:

component (hothouse.model.Model) – 3D component.

animate_sun(camera, latitude, longitude, t_start, t_stop, n_step, fname=None, fps=15, bitrate=1800, multibounce=True, **kwargs)

Create an animation of the sun moving across the scene during the specified time.

Parameters:

• camera (RayBlaster) – Camera ray blaster with one ray per pixel.

• latitude (float) – Latitude in degrees.

• longitude (float) – Longitude in degrees.

• t_start (datetime.datetime) – Start date & time w/ timezone information.

• t_stop (datetime.datetime) – Stop date & time w/ timezone information.

• n_step (int) – Number of steps between t_start and t_stop to include in animation.

• fname (str, optional) – File where animation should be saved. Defaults to None and animation will be shown instead.

• fps (int, optional) – Frame refresh rate in frame per second.

• bitrate (int, optional) – Move bitrate in kilobits per second.

• **kwargs – Additional keyword arguments are passed to the constructor for the SunRayBlaster at each timestep.

Returns:

Animation object.

Return type:

matplotlib.animation.FuncAnimation

components

An instance of a Python list.

compute_count(blasters, accumulators=None, any_direction=True, **kwargs)

Run the raytracer to determine how each ray from a set of blasters will intersect this scene.

Parameters:

• blasters (hothouse.blaster.RayBlaster, list) – One or more blasters to cast on the scene.

• accumulators (dict, optional) –

  Mapping between property names and CastAccumulator or values that can be passed to CastAccumulator.from_kwargs to create an accumulator. Default accumulators (which can be turned off in the provided accumulators dictionary via False) include:

  count (np.ndarray): Number of rays intersecting each
      face.
  flux (np.ndarray): Flux incident on each face.
  tfar (np.ndarray): The smallest distance that a ray
      from any of the blasters traveled before
      intersecting the face (does not include
      reflected/transmitted arrays).
  

• any_direction (bool, optional) – If True, light is deposited on component reguardless of if the blaster rays hit the front or back of a component surface. If False, light is only deposited if the blaster rays hit the front. Defaults to True.

• **kwargs – Additional keyword arguments are passed to compute_count for each blaster.

Returns:

Raytrace results for each accumulated property stored

as a dictionary mapping between component index and results array for each face in the component.

Return type:

dict

compute_flux(light_sources, **kwargs)

Compute the flux on each scene element from a set of light sources. Values will be calculated from the ‘intensity’ attribute of the light source blasters such that the flux will have the same units as intensity.

Parameters:

• light_sources (list) – Set of RayBlasters used to determine the light incident on scene elements.

• **kwargs – Additional keyword arguments are passed to the compute_count method.

Returns:

Mapping from scene component to an array of flux

values for each triangle in the component.

Return type:

dict

compute_flux_density(light_sources, **kwargs)

Compute the flux density on each scene element from a set of light sources. Values will be calculated from the ‘intensity’ attribute of the light source blasters such that the flux density will have units of

[intensity units] / [distance unit from scene] ** 2.

Parameters:

• light_sources (list) – Set of RayBlasters used to determine the light incident on scene elements.

• **kwargs – Additional keyword arguments are passed to the compute_count method.

Returns:

Mapping from scene component to an array of flux

density values for each triangle in the component.

Return type:

dict

compute_hit_count(blaster, **kwargs)

Run the raytracer to determine how many rays will hit each component face in the scene.

Parameters:

• blaster (hothouse.blaster.RayBlaster) – Blaster containing rays to trace.

• **kwargs – Additional keyword arguments are passed to the compute_count method for the blaster.

Returns:

Mapping between component index and arrays of hit

counts for each face in the component geometry.

Return type:

dict

compute_solar_ppfd(latitude, longitude, date, direct_ppfd=None, diffuse_ppfd=None, any_direction=True, multibounce=False, ray_intensity_threshold_abs=0.001, **kwargs)

Compute the photon flux density on each face in the scene from solar irradiance for a given location and time/date.

Parameters:

• latitude (float) – Latitude (in degrees) of the scene.

• longitude (float) – Longitude (in degrees) of the scene.

• date (datetime.datetime) – Time when PPFD should be calculated. This determines the incidence angle of light from the sun.

• direct_ppfd (float, optional) – Direct Photosynthetic Photon Flux Density (PPFD) at the surface of the Earth for the specified location and time. If not provided, the direct_ppfd will be calculated based on the location and time/date.

• diffuse_ppfd (float, optional) – Diffuse Photosynthetic Photon Flux Density (PPFD) at the surface of the Earth for the specified location and time. If not provided, the diffuse_ppfd will be calculated based on the location and time/date.

• any_direction (bool, optional) – If True, light is deposited on component reguardless of if the blaster rays hit the front or back of a component surface. If False, light is only deposited if the blaster rays hit the front. Defaults to True.

• multibounce (bool, optional) – If True, rays should be tracked through reflections/transmission.

• ray_intensity_threshold_abs (float, optional) – Threshold below which rays should no longer be tracked during bounces.

• **kwargs – Additional keyword arguments are passed to the SunRayBlaster constructor.

Returns:

Mapping from scene component to an array of photon flux

density values for each triangle in the component.

Return type:

dict

embree_scene

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

get_sun_blaster(latitude, longitude, date, direct_ppfd=None, diffuse_ppfd=None, zenith=None, **kwargs)

Get a sun blaster that is adjusted for this scene so that the blaster will never intercept a component in the scene. This distance is determined by computing the maximum distance of any vertex in the scene from the ground parameter.

Parameters:

• latitude (float) – Latitude (in degrees) of the scene.

• longitude (float) – Longitude (in degrees) of the scene.

• date (datetime.datetime) – Time when PPFD should be calculated. This determines the incidence angle of light from the sun.

• direct_ppfd (float, optional) – Direct Photosynthetic Photon Flux Density (PPFD) at the surface of the Earth for the specified location and time. If not provided, the direct_ppfd will be calculated based on the location and time/date.

• diffuse_ppfd (float, optional) – Diffuse Photosynthetic Photon Flux Density (PPFD) at the surface of the Earth for the specified location and time. If not provided, the diffuse_ppfd will be calculated based on the location and time/date.

• zenith (np.ndarray) – Position directly above ‘ground’ at distance that sun blaster should be placed.

• **kwargs – Additional keyword arguments are passed to the SunRayBlaster constructor.

Returns:

Blaster tuned to this scene.

Return type:

SunRayBlaster

ground

A numpy array trait type.

limits

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

meshes

An instance of a Python list.

property ncomponents

Number of components in the scene.

Type:

int

north

A numpy array trait type.

post_cast(query_type, output)

Finalize the results from running the ray tracer.

Parameters:

• query_type (QueryType) – Raytrace query type of the output.

• output (object) – Raytracer result.

Returns:

Finalized raytracer result.

Return type:

object

up

A numpy array trait type.

hothouse.sun_calc module

hothouse.sun_calc.incident_power_diffuse(up_dir, norm, area=None)

Calculate the fraction of a diffuse flux that will be deposited on a face.

Parameters:

• up_dir (np.ndarray) – Unit normal to the ground.

• norm (np.ndarray) – Normal vectors for faces the ray(s) intersect.

• area (np.ndarray, None) – Area of the faces the ray(s) intersect. This should also be half the magnitude of the normal vectors so passing it directly if already calculated can save time.

Returns:

Fraction of diffuse flux deposited on each face.

Return type:

np.ndarray

hothouse.sun_calc.incident_power_direct(ray_dir, norm, area=None, any_direction=True)

Calculate the fraction of a ray flux that will be deposited on a face.

Parameters:

• ray_dir (np.ndarray) – Unit vectors for ray(s).

• norm (np.ndarray) – Normal vectors for faces the ray(s) intersect.

• area (np.ndarray, None) – Area of the faces the ray(s) intersect. This should also be half the magnitude of the normal vectors so passing it directly if already calculated can save time.

• any_direction (bool, optional) – If True, power can be deposited from any direction. If False, power can only be deposited if a ray intersects a face from the direction of the face’s normal vector.

Returns:

Fraction of power deposited on each face (cos(theta))

Return type:

np.ndarray

hothouse.sun_calc.norm_along_axis(a, axis=0)

Normalize vectors along a given axis.

Parameters:

• a (np.ndarray) – Matrix to normalize.

• axis (int, optional) – Axis that vectors occupy.

Returns:

Normalized matrix with the same size as a.

Return type:

np.ndarray

hothouse.sun_calc.op_along_axis(op, a, b, axis=0)

Perform an operation between two matrices element by element that match along a specified axis. This is equivalent to performing the element-wise operation on a with an array that repeats b along the other dimensions of a to create an array of the same size as a.

Parameters:

• op (np.ndarray) – Function that performs an operation between two arrays of the same size elementwise.

• a (np.ndarray) – First array in operation.

• b (np.ndarray) – Second array in operation. number of elements along the specified axis.

• axis (int, optional) – Dimension that element-wise operation. should be performed over.

Returns:

Result of operation that is the same size as a.

Return type:

np.ndarray

hothouse.sun_calc.rotate_u(x, theta, u)

Rotate a point arount an axis by an angle.

Parameters:

• x (array) – Position to rotate.

• theta (float) – Angle to rotate by (in radians).

• u (array) – Vector to rotate around.

Returns:

Rotated position.

Return type:

array

hothouse.sun_calc.rotation_matrix(theta, u)

Get the rotation matrix necessary to rotate a 3D point around a unit vector by a specified angle.

Parameters:

• theta (float, np.ndarray) – Angle to rotate by (in radians). If an array is provided and u is a multidimensional array, theta should have the same dimensions as u outside its last dimension (the dimension of the unit vectors).

• u (np.ndarray) – Vector to rotate around. If the array has multiple dimensions, the last dimension is assumed to be the components in each dimension and the resulting rotation matrix will be a composite of rotation matrices for each vector in u in the last two dimension such that it can be used to transform points with the same dimensions as u via numpy.matvec after swapping the last two axes.

Returns

np.ndarray: Rotation matrix.

hothouse.sun_calc.solar_ppfd(latitude, longitude, date, altitude=None, pressure=None, temperature=12.0, eta_par=0.368, eta_photon=4.56)

Determine the Photosynthetic Photon Flux Density (PPFD) received from the sun at a location and time.

Parameters:

• latitude (float) – Latitude in degrees.

• longitude (float) – Longitude in degrees.

• date (datetime.datetime) – Date & time w/ timezone information.

• altitude (float, optional) – Altitude (in meters) used to compute solar position. If not provided, but pressure is, pressure will be used to calculate altitude.

• pressure (float, optional) – Pressure (in Pa) used to compute solar position. If not provided, but altitude is, altitude will be used to calculate pressure.

• temperature (float, optional) – Air temperature (in degrees C) used to compute solar position.

• eta_par (float, optional) – Fraction of solar radiation (assuming black-body spectrum of 5800 K) that is photosynthetically active (wavelengths 400–700 nm).

• eta_photon (float, optional) – Average number of photons per photosynthetically activate unit of radiation (in µmol s−1 W−1).

Returns:

PPFD values for direct and diffuse light.

Return type:

dict

hothouse.sun_calc.stable_arccos(x, rtol=1e-05, atol=1e-08)

Version of arccos that reduces numerical error by handling the special cases of 0, -1, and 1 explicitly.

Parameters:

• x (np.ndarray) – Value(s) to compute arccos of.

• rtol (float, optional) – Relative tolerance to use for detection of special cases.

• atol (float, optional) – Absolute tolerance to use for detection of special cases.

Returns:

Result.

Return type:

np.ndarray

hothouse.sun_calc.stable_arcsin(x, rtol=1e-05, atol=1e-08)

Version of arcsin that reduces numerical error by handling the special cases of 0, -1, and 1 explicitly.

Parameters:

• x (np.ndarray) – Value(s) to compute arcsin of.

• rtol (float, optional) – Relative tolerance to use for detection of special cases.

• atol (float, optional) – Absolute tolerance to use for detection of special cases.

Returns:

Result.

Return type:

np.ndarray

hothouse.sun_calc.stable_arctan(x, rtol=1e-05, atol=1e-08)

Version of arctan that reduces numerical error by handling the special cases of 0, -1, 1, and np.inf explicitly.

Parameters:

• x (np.ndarray) – Value(s) to compute arctan of.

• rtol (float, optional) – Relative tolerance to use for detection of special cases.

• atol (float, optional) – Absolute tolerance to use for detection of special cases.

Returns:

Result.

Return type:

np.ndarray

hothouse.sun_calc.stable_cos(theta, rtol=1e-05, atol=1e-08)

Version of cos that reduces numerical error by reducing the range of the function to [0, 2 * pi) and handling the special cases of 0, pi / 2, pi, 3 * pi / 2 explicitly.

Parameters:

• theta (np.ndarray) – Angle(s) to compute cos of.

• rtol (float, optional) – Relative tolerance to use for detection of special cases.

• atol (float, optional) – Absolute tolerance to use for detection of special cases.

Returns:

Result.

Return type:

np.ndarray

hothouse.sun_calc.stable_sin(theta, rtol=1e-05, atol=1e-08)

Version of sin that reduces numerical error by reducing the range of the function to [0, 2 * pi) and handling the special cases of 0, pi / 2, pi, 3 * pi / 2 explicitly.

Parameters:

• theta (np.ndarray) – Angle(s) to compute sin of.

• rtol (float, optional) – Relative tolerance to use for detection of special cases.

• atol (float, optional) – Absolute tolerance to use for detection of special cases.

Returns:

Result.

Return type:

np.ndarray

hothouse.sun_calc.stable_tan(theta, rtol=1e-05, atol=1e-08)

Version of tan that reduces numerical error by reducing the range of the function to [0, pi) and handling the special cases of 0, pi / 4, pi / 2, 3 * pi / 4 explicitly.

Parameters:

• theta (np.ndarray) – Angle(s) to compute tan of.

• rtol (float, optional) – Relative tolerance to use for detection of special cases.

• atol (float, optional) – Absolute tolerance to use for detection of special cases.

Returns:

Result.

Return type:

np.ndarray

hothouse.traits_support module

class hothouse.traits_support.DependentDefaultHandler(name, depends_on, **kwargs)

Bases: DependentTraitMixin, DefaultHandler

Version of traitlets.DefaultHandler that uses the same method that dynamically returns a default value to update a trait when any of the traits that it depends on are updated.

Parameters:

• name (str) – Name of the trait that the handler will update.

• depends_on (list) – Name(s) of traits that the updated trait depends on to calculate the default.

• **kwargs – Additional keyword arguments are passed to the parent class.

class hothouse.traits_support.DependentProperty(*depends_on, read_only=True, **kwargs)

Bases: DependentTraitMixin, TraitType, EventHandler

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

default(inst)

Evaluate the method to calculate the property value as the default.

Parameters:

inst (traitlets.HasTraits) – Instance that the property belongs to.

Returns:

Calculated property value.

Return type:

object

class hothouse.traits_support.DependentTraitMixin(depends_on, *args, strict=False, change_type=['change', 'clear'], **kwargs)

Bases: object

Mixin for dependent traits.

Parameters:

• depends_on (list) – Name(s) of traits that the updated trait depends on to calculate the default.

• *args – Additional arguments will be passed to the parent class.

• strict (bool, list, optional) – Set of dependencies that should force setting the trait to the default even when it was previously explicitly set. If True, a change to any of the dependencies will force the update.

• change_type (str, list, optional) – Change(s) for which the named trait should be updated.

• **kwargs – Additional keyword arguments are passed to the parent class.

instance_init(inst)

Callback method for initializing observation handlers to handle updates to this trait based on changes to dependencies.

Parameters:

inst (traitlets.HasTraits) – Instance that the trait belongs to.

recalculate(change)

Callback method to recalculate the trait value after an update to one of the traits it depends on.

Parameters:

change (dict) – Metadata about the change being made.

set_default(change)

Callback method to set a metadata flag for the trait indicating that the trait was set to it’s calculated default value.

Parameters:

change (dict) – Metadata about the change being made.

hothouse.traits_support.check_dtype(dtype)

Factory to return a valiator to check the shape of an ndarray trait.

Parameters:

dtype (np.dtype) – Datatype that the validator should check for.

Returns:

Validator that takes a traitlets.TraitType and its

value as input.

Return type:

callable

hothouse.traits_support.check_shape(*dimensions, ignore_trailing=False)

Factory to return a valiator to check the shape of an ndarray trait.

Parameters:

• *dimensions – Arguments are treated as sizes in each dimension.

• ignore_trailing (bool, optional) – If True, the value must only match the provided dimensions and any trailing dimensions will be ignored.

Returns:

Validator that takes a traitlets.TraitType and its

value as input.

Return type:

callable

hothouse.traits_support.dependent_default(name, depends_on, **kwargs)

Decorator to turn a method into a trait default generator that will also cause the trait value to be updated when one of the properties it depends on is updated and the trait has not already been explicitly set.

Parameters:

• name (str) – Trait name.

• depends_on (list) – Name(s) of traits that the updated trait depends on to calculate the default.

• **kwargs – Additional keyword arguments are passed to the DependentDefaultHandler constructor.

Returns:

Handler that can be called on a method

to add the appropriate trait callbacks.

Return type:

DependentDefaultHandler

hothouse.traits_support.dependent_property(*depends_on, **kwargs)

Decorator to turn a method into a property that will be updated when the traits it depends on is updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• **kwargs – Additional keyword arguments are passed to the DependentProperty constructor.

Returns:

Handler that can be called on a method to

add the appropriate trait callbacks.

Return type:

DependentProperty

Module contents

Top-level package for hothouse.

class hothouse.Model(*args: t.Any, **kwargs: t.Any)

Bases: HasTraits

Container for 3D geometries that can be added to scenes.

Parameters:

• vertices (np.ndarray) – Set of vertices used by the geometry.

• indices (np.ndarray) – Indices of vertices comprising each face in the geometry.

• attributes (np.ndarray, optional) – Attributes of each face in the geometry (e.g. color).

• triangles (np.ndarray, optional) – Positions of vertices that make up each face.

• normals (np.ndarray, optional) – Normal unit vectors for each face.

• vertex_normals (np.ndarray, optional) – Normal unit vectors for each vertex.

areas

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

attributes

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

face_colors

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

classmethod from_file(filename, **kwargs)

Create a model from a 3D mesh loaded from a file.

Parameters:

• filename (str) – Path to file.

• **kwargs – Additional keyword arguments are passed to either from_obj or from_ply after determine the file type from its extension.

Returns:

Model containing the loaded geometry.

Return type:

Model

Raises:

ValueError – If filename has an unsupported extension.

classmethod from_obj(filename, attributes=None, **kwargs)

Create a model from a 3D mesh described by an ObjWavefront file.

Parameters:

• filename (str) – Path to ObjWavefront file.

• attributes (dict, optional) – Mapping of attribute name to an array of values for that attribute at each face.

• **kwargs – Additional keyword arguments are passed to the class constructor.

Returns:

Model containing the loaded geometry.

Return type:

Model

classmethod from_ply(filename, attributes=None, **kwargs)

Create a model from a 3D mesh described by a ply file.

Parameters:

• filename (str) – Path to ply file.

• attributes (dict, optional) – Mapping of attribute name to an array of values for that attribute at each face.

• **kwargs – Additional keyword arguments are passed to the class constructor.

Returns:

Model containing the loaded geometry.

Return type:

Model

property geometry

Model geometry.

Type:

pythreejs.BufferGeometry

indices

A numpy array trait type.

property nface

Number of faces in the model.

Type:

int

normals

A numpy array trait type.

property nvert

Number of vertices in the model.

Type:

int

translate(delta)

Shift the vertices in the model geometry.

Parameters:

delta (np.ndarray) – Shift to apply.

triangles

A numpy array trait type.

triangles_f4

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

vertex_colors

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

vertex_normals

A numpy array trait type.

vertices

A numpy array trait type.

class hothouse.OrthographicRayBlaster(*args: t.Any, **kwargs: t.Any)

Bases: RayBlaster

Container for orthographic set of rays in a square.

Parameters:

• center (np.ndarray) – Center of the set of rays.

• forward (np.ndarray) – Unit vector giving the ray direction.

• up (np.ndarray, optional) – Unit vector giving the y direction of the ray pattern. Required if east not provided.

• east (np.ndarray, optional) – Unit vector giving the x direction of the ray pattern. Required if up not provided.

• width (float, optional) – Width of the ray pattern.

• height (float, optional) – Height of the ray pattern.

• nx (int, optional) – Number of rays distributed in the x (east) direction.

• ny (int, optional) – Number of rays distributed in the y (up) direction.

• period (np.ndarray, optional) – Number of times the rays should be repeated in the up & east directions.

• intensity (float, optional) – Total intensity of light in rays.

• intensity_density (float, optional) – Intensity of light in rays per unit area. If provided and intensity is not, this will be used to calculate intensity.

• **kwargs – Additional keyword arguments are passed to RayBlaster.

cast_once(scene, verbose_output=False, query_type=QueryType.DISTANCE, dists=None, **kwargs)

Run the embree raytrace once on a scene.

Parameters:

• scene (hothouse.scene.Scene) – Scene to raytrace.

• verbose_output (bool, optional) – If True, output a dictionary of all ray properties.

• query_type (QueryType, optional) – Raytrace query type controlling the output.

• dists (np.ndarray, optional) – Array of distances for each ray that should be updated.

• **kwargs – Additional keyword arguments are passed to the RayBlaster method.

Returns:

Ray trace result.

Return type:

np.ndarray, dict

center

A numpy array trait type.

east

A numpy array trait type.

forward

A numpy array trait type.

height

A casting version of the float trait.

intensity

A casting version of the float trait.

intensity_density

A casting version of the float trait.

is_periodic

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

nx

A casting version of the int trait.

ny

A casting version of the int trait.

period

A numpy array trait type.

up

A numpy array trait type.

width

A casting version of the float trait.

class hothouse.Scene(*args: t.Any, **kwargs: t.Any)

Bases: HasTraits

Container for component geometries that will be traced and properties of the context in which they reside.

Parameters:

• ground (np.ndarray, optional) – Scene center.

• up (np.ndarray, optional) – Normal unit vector for the ground.

• north (np.ndarray, optional) – Unit vector for the north cardinal direction.

• components (list, optional) – 3D components in the scene.

• meshes (list, optional) – 3D geometries for the components in the scene.

• embree_scene (pyembree.EmbreeScene, optional)

add_component(component)

Add a component to the scene.

Parameters:

component (hothouse.model.Model) – 3D component.

animate_sun(camera, latitude, longitude, t_start, t_stop, n_step, fname=None, fps=15, bitrate=1800, multibounce=True, **kwargs)

Create an animation of the sun moving across the scene during the specified time.

Parameters:

• camera (RayBlaster) – Camera ray blaster with one ray per pixel.

• latitude (float) – Latitude in degrees.

• longitude (float) – Longitude in degrees.

• t_start (datetime.datetime) – Start date & time w/ timezone information.

• t_stop (datetime.datetime) – Stop date & time w/ timezone information.

• n_step (int) – Number of steps between t_start and t_stop to include in animation.

• fname (str, optional) – File where animation should be saved. Defaults to None and animation will be shown instead.

• fps (int, optional) – Frame refresh rate in frame per second.

• bitrate (int, optional) – Move bitrate in kilobits per second.

• **kwargs – Additional keyword arguments are passed to the constructor for the SunRayBlaster at each timestep.

Returns:

Animation object.

Return type:

matplotlib.animation.FuncAnimation

components

An instance of a Python list.

compute_count(blasters, accumulators=None, any_direction=True, **kwargs)

Run the raytracer to determine how each ray from a set of blasters will intersect this scene.

Parameters:

• blasters (hothouse.blaster.RayBlaster, list) – One or more blasters to cast on the scene.

• accumulators (dict, optional) –

  Mapping between property names and CastAccumulator or values that can be passed to CastAccumulator.from_kwargs to create an accumulator. Default accumulators (which can be turned off in the provided accumulators dictionary via False) include:

  count (np.ndarray): Number of rays intersecting each
      face.
  flux (np.ndarray): Flux incident on each face.
  tfar (np.ndarray): The smallest distance that a ray
      from any of the blasters traveled before
      intersecting the face (does not include
      reflected/transmitted arrays).
  

• any_direction (bool, optional) – If True, light is deposited on component reguardless of if the blaster rays hit the front or back of a component surface. If False, light is only deposited if the blaster rays hit the front. Defaults to True.

• **kwargs – Additional keyword arguments are passed to compute_count for each blaster.

Returns:

Raytrace results for each accumulated property stored

as a dictionary mapping between component index and results array for each face in the component.

Return type:

dict

compute_flux(light_sources, **kwargs)

Compute the flux on each scene element from a set of light sources. Values will be calculated from the ‘intensity’ attribute of the light source blasters such that the flux will have the same units as intensity.

Parameters:

• light_sources (list) – Set of RayBlasters used to determine the light incident on scene elements.

• **kwargs – Additional keyword arguments are passed to the compute_count method.

Returns:

Mapping from scene component to an array of flux

values for each triangle in the component.

Return type:

dict

compute_flux_density(light_sources, **kwargs)

Compute the flux density on each scene element from a set of light sources. Values will be calculated from the ‘intensity’ attribute of the light source blasters such that the flux density will have units of

[intensity units] / [distance unit from scene] ** 2.

Parameters:

• light_sources (list) – Set of RayBlasters used to determine the light incident on scene elements.

• **kwargs – Additional keyword arguments are passed to the compute_count method.

Returns:

Mapping from scene component to an array of flux

density values for each triangle in the component.

Return type:

dict

compute_hit_count(blaster, **kwargs)

Run the raytracer to determine how many rays will hit each component face in the scene.

Parameters:

• blaster (hothouse.blaster.RayBlaster) – Blaster containing rays to trace.

• **kwargs – Additional keyword arguments are passed to the compute_count method for the blaster.

Returns:

Mapping between component index and arrays of hit

counts for each face in the component geometry.

Return type:

dict

compute_solar_ppfd(latitude, longitude, date, direct_ppfd=None, diffuse_ppfd=None, any_direction=True, multibounce=False, ray_intensity_threshold_abs=0.001, **kwargs)

Compute the photon flux density on each face in the scene from solar irradiance for a given location and time/date.

Parameters:

• latitude (float) – Latitude (in degrees) of the scene.

• longitude (float) – Longitude (in degrees) of the scene.

• date (datetime.datetime) – Time when PPFD should be calculated. This determines the incidence angle of light from the sun.

• direct_ppfd (float, optional) – Direct Photosynthetic Photon Flux Density (PPFD) at the surface of the Earth for the specified location and time. If not provided, the direct_ppfd will be calculated based on the location and time/date.

• diffuse_ppfd (float, optional) – Diffuse Photosynthetic Photon Flux Density (PPFD) at the surface of the Earth for the specified location and time. If not provided, the diffuse_ppfd will be calculated based on the location and time/date.

• any_direction (bool, optional) – If True, light is deposited on component reguardless of if the blaster rays hit the front or back of a component surface. If False, light is only deposited if the blaster rays hit the front. Defaults to True.

• multibounce (bool, optional) – If True, rays should be tracked through reflections/transmission.

• ray_intensity_threshold_abs (float, optional) – Threshold below which rays should no longer be tracked during bounces.

• **kwargs – Additional keyword arguments are passed to the SunRayBlaster constructor.

Returns:

Mapping from scene component to an array of photon flux

density values for each triangle in the component.

Return type:

dict

embree_scene

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

get_sun_blaster(latitude, longitude, date, direct_ppfd=None, diffuse_ppfd=None, zenith=None, **kwargs)

Get a sun blaster that is adjusted for this scene so that the blaster will never intercept a component in the scene. This distance is determined by computing the maximum distance of any vertex in the scene from the ground parameter.

Parameters:

• latitude (float) – Latitude (in degrees) of the scene.

• longitude (float) – Longitude (in degrees) of the scene.

• date (datetime.datetime) – Time when PPFD should be calculated. This determines the incidence angle of light from the sun.

• direct_ppfd (float, optional) – Direct Photosynthetic Photon Flux Density (PPFD) at the surface of the Earth for the specified location and time. If not provided, the direct_ppfd will be calculated based on the location and time/date.

• diffuse_ppfd (float, optional) – Diffuse Photosynthetic Photon Flux Density (PPFD) at the surface of the Earth for the specified location and time. If not provided, the diffuse_ppfd will be calculated based on the location and time/date.

• zenith (np.ndarray) – Position directly above ‘ground’ at distance that sun blaster should be placed.

• **kwargs – Additional keyword arguments are passed to the SunRayBlaster constructor.

Returns:

Blaster tuned to this scene.

Return type:

SunRayBlaster

ground

A numpy array trait type.

limits

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

meshes

An instance of a Python list.

property ncomponents

Number of components in the scene.

Type:

int

north

A numpy array trait type.

post_cast(query_type, output)

Finalize the results from running the ray tracer.

Parameters:

• query_type (QueryType) – Raytrace query type of the output.

• output (object) – Raytracer result.

Returns:

Finalized raytracer result.

Return type:

object

up

A numpy array trait type.

class hothouse.SunRayBlaster(*args: t.Any, **kwargs: t.Any)

Bases: OrthographicRayBlaster

Container for an orthographic set of rays with properties set based on the position of the sun for a given location and date/time.

Parameters:

• latitude (float) – Location latitude (in degrees).

• longitude (float) – Location longitude (in degrees).

• date (datetime.datetime) – Date/time.

• ground (np.ndarray) – Position of the center of the ray projection on the ground.

• zenith (np.ndarray) – Position directly above ‘ground’ at distance that sun blaster should be placed.

• north (np.ndarray) – Direction of north on ground from ‘ground’.

• solar_altitude (float) – Angle of sun above the horizon.

• solar_azimuth (float) – Angle of sun around the horizon from north.

• solar_distance (float) – Distance of sun from ground.

• scene_limits (np.ndarray) – Set of points defining the bounds of the scene.

• altitude (float, optional) – Altitude (in meters) used to compute solar position. If not provided, but pressure is, pressure will be used to calculate altitude.

• pressure (float, optional) – Pressure (in Pa) used to compute solar position. If not provided, but altitude is, altitude will be used to calculate pressure.

• temperature (float, optional) – Air temperature (in degrees C) used to compute solar position.

• eta_par (float, optional) – Fraction of solar radiation (assuming black-body spectrum of 5800 K) that is photosynthetically active (wavelengths 400–700 nm).

• eta_photon (float, optional) – Average number of photons per photosynthetically activate unit of radiation (in µmol s−1 W−1).

altitude

A float trait.

date

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

eta_par

A float trait.

eta_photon

A float trait.

classmethod get_solar_direction(latitude, longitude, date, up, north, **kwargs)

Get the direction that rays from the sun will travel for a given location, time, and orientation.

Parameters:

• latitude (float) – Location latitude (in degrees).

• longitude (float) – Location longitude (in degrees).

• date (datetime.datetime) – Date/time.

• up (np.ndarray, optional) – Normal unit vector for the ground.

• north (np.ndarray) – Unit vector for the north cardinal direction.

• **kwargs – Additional keyword arguments are passed to SunRayBlaster instance.

Returns:

Unit vector in the direction of sun rays.

Return type:

np.ndarray

ground

A numpy array trait type.

latitude

A float trait.

limits_east

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

limits_up

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

longitude

A float trait.

north

A numpy array trait type.

pressure

A float trait.

scene_limits

A numpy array trait type.

solar_altitude

A casting version of the float trait.

solar_azimuth

A casting version of the float trait.

solar_distance

A casting version of the float trait.

solar_east

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

solar_ppfd

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

solar_rotation(point, is_ray=False)

Rotate a point according to same rotation that moves sun from the zenith to its location in the sky.

Parameters:

• point (array) – 3D point to rotate

• is_ray (bool, optional) – If True, the point is treated as a ray and will not be shifted prior to rotation.

solpos_info

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.

temperature

A float trait.

zenith

A numpy array trait type.

zenith_direction

Event handler that allows methods to be treated as cached properties that are updated when the traits it depends on are updated.

Parameters:

• *depends_on – Name(s) of traits that the property depends on.

• read_only (bool, optional) – If True, the property will be read-only. Defaults to True.

• **kwargs – Additional keyword arguments are passed to the traitlets.TraitType constructor.