honeybee_radiance.sensorgrid module

A grid of sensors.

class honeybee_radiance.sensorgrid.SensorGrid(identifier, sensors)[source]

Bases: object

A grid of sensors.

Parameters:

  • identifier – Text string for a unique SensorGrid ID. Must not contain spaces or special characters. This will be used to identify the object in the exported Radiance files.

  • sensors – A collection of Sensors.

Properties:

  • identifier

  • display_name

  • sensors

  • positions

  • directions

  • room_identifier

  • light_path

  • mesh

  • base_geometry

  • group_identifier

  • full_identifier

ToString()[source]

Overwrite ToString .NET method.

duplicate()[source]

Get a copy of this object.

enclosure_info_dict(model, air_boundary_distance=0)[source]

Get a dictionary with information about sensor relation to rooms.

This can be written as a JSON in order to map sensors with appropriate energy simulation results in thermal mapping workflows.

Parameters:

  • model – A honeybee Model object which will be used to identify the rooms/enclosure that each sensor in the grid is contained within.

  • air_boundary_distance – An optional number to set the distance from air boundaries over which values should be interpolated. Using 0 will assume a hard edge between Rooms of the same radiant enclosures. (Default: 0).

classmethod from_dict(ag_dict)[source]

Create a sensor grid from a dictionary in the following format.

{
"type": "SensorGrid",
"identifier": str,  # SensorGrid identifier
"display_name": str,  # SensorGrid display name
"sensors": [],  # list of Sensor dictionaries
'room_identifier': str,  # optional room identifier
'group_identifier': str,  # optional group identifier
'light_path':  []  # optional list of lists for light path
}
classmethod from_face3d(identifier, faces, x_dim, y_dim=None, offset=0, flip=False)[source]

Create a sensor grid from an array of ladybug_geometry Face3D.

The Face3D will be converted into a gridded mesh using the input x_dim and y_dim. The centroids of the mesh faces will be used to create the sensor positions and the normals of the faces will set the directions. The mesh will be assigned to the resulting SensorGrid’s mesh property and the Face3Ds assigned to the base_geometry.

Parameters:

  • identifier – Text string for a unique SensorGrid ID. Must not contain spaces or special characters. This will be used to identify the object across a model and in the exported Radiance files.

  • faces – An array of ladybug_geometry Face3Ds from which a SensorGrid will be generated.

  • x_dim – The x dimension of the grid cells as a number.

  • y_dim – The y dimension of the grid cells as a number. Default is None, which will assume the same cell dimension for y as is set for x.

  • offset – A number for how far to offset the grid from the base face.

  • flip – Set to True to have the mesh normals reversed from the direction of this face and to have the offset input move the mesh in the opposite direction from this face normal. Defaults to False, which means the normal direction of the face will be used as the direction of the sensor grids.

static from_face3d_arrays(base_identifier, face_arrays, x_dim, y_dim=None, offset=0, flip=False)[source]

Get an array of SensorGrids from an matrix (list of lists) of Face3Ds.

This method uses the from_face3d classmethod but includes checks to catch cases where the input Face3Ds cannot support the generation of quad grids. In this case, the invalid SensorGrid will not be generated and will be excluded form the output list of SensorGrids.

Parameters:

  • base_identifier – Text string for a unique SensorGrid ID, which will be used as a base for all of the output SensorGrid IDs. Must not contain spaces or special characters.

  • faces – An matrix (list of lists) of ladybug_geometry Face3Ds from which SensorGrids will be generated.

  • x_dim – The x dimension of the grid cells as a number.

  • y_dim – The y dimension of the grid cells as a number. Default is None, which will assume the same cell dimension for y as is set for x.

  • offset – A number for how far to offset the grid from the base face.

  • flip – Set to True to have the mesh normals reversed from the direction of this face and to have the offset input move the mesh in the opposite direction from this face normal. Defaults to False, which means the normal direction of the face will be used as the direction of the sensor grids.

classmethod from_file(file_path, start_line=None, end_line=None, identifier=None)[source]

Create a sensor grid from a sensor (.pts) file.

The sensors must be structured as

x1, y1, z1, dx1, dy1, dz1 x2, y2, z2, dx2, dy2, dz2 …

The lines that start with # will be considred as commented lines and won’t be loaded. However, these commented lines are still considered in total line count for the start_line and end_line inputs.

Parameters:

  • file_path – Full path to sensors file

  • start_line – Start line including the comments (default: 0).

  • end_line – End line as an integer including the comments (default: last line in file).

  • identifier – Text string for a unique SensorGrid ID. Must not contain spaces or special characters. This will be used to identify the object across a model and in the exported Radiance files. If None, the file name will be used. (Default: None)

classmethod from_mesh3d(identifier, mesh)[source]

Create a sensor grid from a ladybug_geometry Mesh3D.

The centroids of the mesh faces will be used to create the sensor positions and the normals of the faces will set the directions. The mesh will be assigned to the resulting SensorGrid’s mesh property.

Parameters:

  • identifier – Text string for a unique SensorGrid ID. Must not contain spaces or special characters. This will be used to identify the object across a model and in the exported Radiance files.

  • mesh – A ladybug_geometry Mesh3D.

classmethod from_mesh3d_radial(identifier, mesh, dir_count=8, start_vector=Vector3D(0.00, -1.00, 0.00), mesh_radius=0)[source]

Create a sensor grid from radial directions around centroids of a Mesh3D.

This type of sensor grid is particularly helpful for studies of multiple view directions, such as imageless glare studies.

Parameters:

  • identifier – Text string for a unique SensorGrid ID. Must not contain spaces or special characters. This will be used to identify the object across a model and in the exported Radiance files.

  • mesh – A ladybug_geometry Mesh3D from which the sensor grid will be generated.

  • dir_count – A positive integer for the number of radial directions to be generated around each position. (Default: 8).

  • start_vector – A Vector3D to set the start direction of the generated directions. This can be used to orient the resulting sensors to specific parts of the scene. It can also change the elevation of the resulting directions since this start vector will always be rotated in the XY plane to generate the resulting directions.

  • mesh_radius – An optional number that can be used to generate a Mesh3D that is aligned with the resulting sensors and will automatically be assigned to the grid’s mesh property. Such meshes will resemble a circle around each sensor with the specified radius and will contain triangular faces that can be colored with simulation results. If zero, no mesh will be generated for the sensor grid. (Default: 0).

classmethod from_planar_positions(identifier, positions, plane_normal)[source]

Create a sensor grid from a collection of positions with the same direction.

Parameters:

  • identifier – Text string for a unique SensorGrid ID. Must not contain spaces or special characters. This will be used to identify the object across a model and in the exported Radiance files.

  • positions – A list of (x, y ,z) tuples for position of sensors.

  • plane_normal – (x, y, z) tuples for direction of sensors.

classmethod from_position_and_direction(identifier, positions, directions)[source]

Create a sensor grid from a collection of positions and directions.

The length of positions and directions should be the same. In case the lists have different lengths the shorter list will be used as the reference.

Parameters:

  • identifier – Text string for a unique SensorGrid ID. Must not contain spaces or special characters. This will be used to identify the object across a model and in the exported Radiance files.

  • positions – A list of (x, y ,z) tuples for position of sensors.

  • directions – A list of (x, y, z) tuples for direction of sensors.

classmethod from_positions_radial(identifier, positions, dir_count=8, start_vector=Vector3D(0.00, -1.00, 0.00), mesh_radius=0)[source]

Create a sensor grid from radial directions around sensor positions.

This type of sensor grid is particularly helpful for studies of multiple view directions, such as imageless glare studies.

Parameters:

  • identifier – Text string for a unique SensorGrid ID. Must not contain spaces or special characters. This will be used to identify the object across a model and in the exported Radiance files.

  • positions – A list of (x, y ,z) tuples for position of sensors.

  • dir_count – A positive integer for the number of radial directions to be generated around each position. (Default: 8).

  • start_vector – A Vector3D to set the start direction of the generated directions. This can be used to orient the resulting sensors to specific parts of the scene. It can also change the elevation of the resulting directions since this start vector will always be rotated in the XY plane to generate the resulting directions. (Default: (0, -1, 0)).

  • mesh_radius – An optional number that can be used to generate a Mesh3D that is aligned with the resulting sensors and will automatically be assigned to the grid’s mesh property. Such meshes will resemble a circle around each sensor with the specified radius and will contain triangular faces that can be colored with simulation results. If zero, no mesh will be generated for the sensor grid. (Default: 0).

info_dict(model=None)[source]

Get a dictionary with information about the SensorGrid.

This can be written as a JSON into a model radiance folder to narrow down the number of aperture groups that have to be run with this sensor grid.

Parameters:

model – A honeybee Model object which will be used to identify the aperture groups that will be run with this sensor grid.

move(moving_vec)[source]

Move this sensor grid along a vector.

Parameters:

moving_vec – A ladybug_geometry Vector3D with the direction and distance to move the sensor.

static radial_positions_mesh(positions, dir_count=8, start_vector=Vector3D(0.00, -1.00, 0.00), mesh_radius=1)[source]

Generate a Mesh3D resembling a circle around each position.

Parameters:

  • positions – A list of (x, y ,z) tuples for position of sensors.

  • dir_count – A positive integer for the number of radial directions to be generated around each position. (Default: 8).

  • start_vector – A Vector3D to set the start direction of the generated directions. (Default: (0, -1, 0)).

  • mesh_radius – A number for the radius of the radial mesh to be generated around each sensor. (Default: 1).

reflect(plane)[source]

Reflect this sensor grid across a plane.

Parameters:

plane – A ladybug_geometry Plane across which the object will be reflected.

rotate(axis, angle, origin)[source]

Rotate this sensor grid by a certain angle around an axis and origin.

Parameters:

  • axis – Rotation axis as a Vector3D.

  • angle – An angle for rotation in degrees.

  • origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

rotate_xy(angle, origin)[source]

Rotate this sensor grid counterclockwise in the world XY plane by an angle.

Parameters:

  • angle – An angle in degrees.

  • origin – A ladybug_geometry Point3D for the origin around which the object will be rotated.

scale(factor, origin=None)[source]

Scale this sensor grid by a factor from an origin point.

Parameters:

  • factor – A number representing how much the object should be scaled.

  • origin – A ladybug_geometry Point3D representing the origin from which to scale. If None, it will be scaled from the World origin (0, 0, 0).

to_dict()[source]

Convert SensorGrid to a dictionary.

to_file(folder, file_name=None, mkdir=False, ignore_group=False)[source]

Write this sensor grid to a Radiance sensors file.

Parameters:

  • folder – Target folder. If grid is part of a sensor group identifier it will be written to a subfolder with group identifier name.

  • file_name – Optional file name without extension. (Default: self.identifier)

  • mkdir – A boolean to indicate if the folder should be created in case it doesn’t exist already. (Default: False).

  • ignore_group – A boolean to indicate if creating a new subfolder for sensor group should be ignored. (Default: False).

Returns:

Full path to newly created file.

to_files(folder, count, base_name=None, mkdir=False)[source]

Split this sensor grid and write them to several files.

This method writes the files directly to the folder and doesn’t create a subfolder for sensor groups if any. You can add the group subfolder to folder before calling the method.

Parameters:

  • folder – Target folder.

  • count – Number of files.

  • base_name – Optional text string for a unique base name for the sensor grid files. (Default: self.identifier)

  • mkdir – A boolean to indicate if the folder should be created in case it doesn’t exist already (Default: False).

Returns:

A list of dicts containing the grid name, path to the grid and full path to the grid.

to_json(folder, file_name=None, mkdir=False, ignore_group=False)[source]

Write this sensor grid to a JSON file.

Parameters:

  • folder – Target folder. If grid is part of a sensor group identifier it will be written to a subfolder with group identifier name.

  • file_name – Optional file name without extension. (Default: self.identifier)

  • mkdir – A boolean to indicate if the folder should be created in case it doesn’t exist already. (Default: False).

  • ignore_group – A boolean to indicate if creating a new subfolder for sensor group should be ignored. (Default: False).

Returns:

Full path to newly created file.

to_radial_grid(dir_count=8, start_vector=Vector3D(0.00, -1.00, 0.00), mesh_radius=0)[source]

Get a radial sensor grid using the positions of this grid as a base.

All properties of this grid will be transferred to the new grid, including the identifier, room_identifier, etc. The mesh will be recomputed based on the input mesh_radius but any base_geometry will be transferred.

Note that calling this method on a SensorGrid that is already formatted as a radial grid will result in a lot of unwanted duplication of sensors.

Parameters:

  • dir_count – A positive integer for the number of radial directions to be generated around each position. (Default: 8).

  • start_vector – A Vector3D to set the start direction of the generated directions. This can be used to orient the resulting sensors to specific parts of the scene. It can also change the elevation of the resulting directions since this start vector will always be rotated in the XY plane to generate the resulting directions. (Default: (0, -1, 0)).

  • mesh_radius – An optional number that can be used to generate a Mesh3D that is aligned with the resulting sensors and will automatically be assigned to the grid’s mesh property. Such meshes will resemble a circle around each sensor with the specified radius and will contain triangular faces that can be colored with simulation results. If zero, no mesh will be generated for the sensor grid. (Default: 0).

to_radiance()[source]

Return sensors grid as a Radiance string.

property base_geometry

Get or set an optional array of ladybug_geometry Face3D used to make the grid.

There are no restrictions on how this property relates to the sensors and it is provided only to assist with the display of the grid when the number of sensors or the mesh is too large to be practically visualized.

property count

Get the number of sensors.

property directions

Get a generator of sensor directions as x, y , z.

property display_name

Get or set a string for the object name without any character restrictions.

If not set, this will be equal to the identifier.

property full_identifier

Get full identifier for a sensor grid.

For a sensor grid with group identifier it will be group_identifier/identifier

property group_identifier

Get or set text for the group identifier to which this SensorGrid belongs.

This will be used in the write to radiance folder method to write all the grids with the same group identifier under the same subfolder.

You may use / in name to identify nested grid groups. For example floor_1/living_room create a sensor grid under living_room/floor_1 subfolder.

If None, the grid will be written to the root of grids folder.

property identifier

Get or set text for a unique SensorGrid identifier.

property light_path

Get or set list of lists for the light path from the grid to the sky.

Each sub-list contains identifiers of aperture groups through which light passes. (eg. [[‘SouthWindow1’], [‘__static_apertures__’, ‘NorthWindow2’]]). Setting this property will override any auto-calculation of the light path from the model upon export to the simulation.

property mesh

Get or set an optional ladybug_geometry Mesh3D that aligns with the sensors.

Note that the number of sensors in the grid must match the number of faces or the number vertices within the Mesh3D.

property positions

Get a generator of sensor positions as x, y, z.

property room_identifier

Get or set text for the Room identifier to which this SensorGrid belongs.

This will be used in the info_dict method to narrow down the number of aperture groups that have to be run with this sensor grid. If None, the grid will be run with all aperture groups in the model.

property sensors

Get or set a tuple of Sensor objects for the grid sensors.