ladybug_radiance.study.directsun module

Class for visualizing the direct sun hours falling onto a mesh.

class ladybug_radiance.study.directsun.DirectSunStudy(vectors, study_mesh, context_geometry, timestep=1, offset_distance=0, by_vertex=False, sim_folder=None, use_radiance_mesh=False)[source]

Bases: object

Visualize the direct sun hours falling onto a study_mesh.

Such direct sun calculations can be used for shadow studies of outdoor environments or can be used to estimate glare potential from direct sun on the indoors.

Parameters:

  • vectors – Sun vectors, which will be used to determine the number of hours of direct sun received by the test study_mesh. These vectors can be computed using the ladybug.sunpath module.

  • study_mesh – A ladybug geometry Mesh3D, which represents the geometry on which the direct sun is being studied.

  • context_geometry – A list of ladybug geometry Face3D and/or Mesh3D that can block the sun.

  • timestep – A positive integer for the number of timesteps per hour at which the sun vectors were generated. This is used to correctly interpret the time duration represented by each of the input sun vectors. (Default: 1 for 1 vector per hour).

  • offset_distance – An optional number to offset the sensor points before the vectors are cast through the context_geometry. (Default: 0).

  • by_vertex – A boolean to indicate whether the study should be run for each vertex of the study_mesh (True) or each face of the study mesh (False). (Default: False).

  • sim_folder – An optional path to a folder where the simulation files will be written. If None, a temporary directory will be used. (Default: None).

  • use_radiance_mesh – A boolean to note whether input Mesh3D should be translated to Radiance Meshes for simulation or whether they should simply have their faces translated to Radiance polygons. For complex context geometry, Radiance meshes will use less memory but they take a longer time to prepare compared to polygons. (Default: False).

Properties:

  • vectors

  • timestep

  • study_mesh

  • context_geometry

  • offset_distance

  • by_vertex

  • sim_folder

  • use_radiance_mesh

  • study_points

  • study_normals

  • intersection_matrix

  • direct_sun_hours

ToString()[source]

Overwrite .NET ToString.

compute()[source]

Compute the direct sun hour values of the study.

Note that this method is automatically called under the hood when accessing any results of the study and these results have not already been computed. So using this method is not necessary to correctly use this class. However, explicitly calling this method can help control when the time consuming part of the study runs, which is particularly helpful for larger studies.

draw(legend_parameters=None)[source]

Draw a colored study_mesh, compass, graphic/legend, and title.

Parameters:

legend_parameters – An optional LegendParameter object to change the display of the direct sun study. If None, default legend parameters will be used. (Default: None).

Returns:

A tuple with three values.

  • colored_mesh – A colored Mesh3D for the study results.

  • graphic – A GraphicContainer for the colored mesh, indicating the

    legend and title location for the study.

  • title – Text for the title of the study.

property by_vertex

Get or set a boolean for whether the study should be run for each vertex.

property context_geometry

Get or set a tuple of Face3D and Mesh3D for the geometry that can block sun.

property direct_sun_hours

Get a list of values for the number of hours falling on the study_mesh.

property intersection_matrix

Get a list of lists for the intersection matrix computed by the study.

property offset_distance

Get or set a number for the offset distance used in the study.

property sim_folder

Get or set text for the path where the simulation files are written.

property study_mesh

Get or set a SkyMatrix object for the sky used in the study.

property study_normals

Get a tuple of Vector3Ds for the normals of the study.

property study_points

Get a tuple of Point3Ds for the points of the study.

property timestep

Get or set an integer for the timestep at which the vectors were generated.

property use_radiance_mesh

Get or set a boolean for whether Radiance Meshes are used in the simulation.

property vectors

Get or set a list of vectors for the sun vectors used in the study.