grid

honeybee-radiance grid

Commands for generating and modifying sensor grids.

honeybee-radiance grid [OPTIONS] COMMAND [ARGS]...

enclosure-info

Get a JSON of radiant enclosure information from a .pts file of a sensor grid.

Args:
model_file: Full path to a Model JSON file (HBJSON) or a Model pkl (HBpkl) file.
grid-file: Full path to a sensor grid file (.pts).
honeybee-radiance grid enclosure-info [OPTIONS] MODEL_FILE GRID_FILE

Options

-d, --air-boundary-distance <air_boundary_distance>

A 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. This can include the units of the distance (eg. 3ft) or, if no units are provided the value will be interpreted in the honeybee model units.

Default

2m

-f, --output-file <output_file>

Optional output file for the generated radiant enclosure JSON. By default this will be printed to stdout

Arguments

MODEL_FILE

Required argument

GRID_FILE

Required argument

from-exterior-apertures

Generate SensorGrids from the exterior Faces of a honeybee model.

Args:
model_file: Full path to a HBJSON or HBPkl Model file.
honeybee-radiance grid from-exterior-apertures [OPTIONS] MODEL_FILE

Options

-s, --grid-size <grid_size>

A number for the dimension of the mesh grid cells. This can include the units of the distance (eg. 1ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default

0.5m

-o, --offset <offset>

A number for the distance at which the the sensor grid should be offset from the apertures. This can include the units of the distance (eg. 3ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default

0.1m

-t, --aperture-type <aperture_type>

Text to specify the type of aperture that will be used to generate grids. Note that only Faces with Outdoors boundary conditions will be used, meaning that most Floors will typically be excluded unless they represent the underside of a cantilever. Choose from Window, Skylight, All.

Default

All

--include-mesh, -xm, --exclude-mesh

Flag to note whether to include a Mesh3D object that aligns with the grid positions under the “mesh” property of each grid. Excluding the mesh can reduce size but will mean Radiance results cannot be visualized as colored meshes.

Default

True

-r, --room <room>

Room identifier to specify the room for which sensor grids should be generated. You can pass multiple rooms (each preceded by -r). By default, all rooms get sensor grids joined into a single grid.

--write-json, -pts, --write-pts

Flag to note whether output data collection should be in JSON format or the typical CSV-style format of the Radiance .pts files.

Default

True

--folder <folder>

Optional output folder. If specified, the –output-file will be ignored and each sensor grid will be written into its own .json or .pts file within the folder.

-f, --output-file <output_file>

Optional file to output the JSON or CSV string of the sensor grids. By default this will be printed to stdout

Default

-

Arguments

MODEL_FILE

Required argument

from-exterior-faces

Generate SensorGrids from the exterior Faces of a honeybee model.

Args:
model_file: Full path to a HBJSON or HBPkl Model file.
honeybee-radiance grid from-exterior-faces [OPTIONS] MODEL_FILE

Options

-s, --grid-size <grid_size>

A number for the dimension of the mesh grid cells. This can include the units of the distance (eg. 1ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default

0.5m

-o, --offset <offset>

A number for the distance at which the the sensor grid should be offset from the faces. This can include the units of the distance (eg. 3ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default

0.1m

-t, --face-type <face_type>

Text to specify the type of face that will be used to generate grids. Note that only Faces with Outdoors boundary conditions will be used, meaning that most Floors will typically be excluded unless they represent the underside of a cantilever. Choose from Wall, Roof, Floor, All.

Default

Wall

--full-geometry, -p, --punched-geometry

Flag to note whether the punched_geometry of the faces should be used with the areas of sub-faces removed from the grid or the full geometry should be used.

--include-mesh, -xm, --exclude-mesh

Flag to note whether to include a Mesh3D object that aligns with the grid positions under the “mesh” property of each grid. Excluding the mesh can reduce size but will mean Radiance results cannot be visualized as colored meshes.

Default

True

-r, --room <room>

Room identifier to specify the room for which sensor grids should be generated. You can pass multiple rooms (each preceded by -r). By default, all rooms get sensor grids joined into a single grid.

--write-json, -pts, --write-pts

Flag to note whether output data collection should be in JSON format or the typical CSV-style format of the Radiance .pts files.

Default

True

--folder <folder>

Optional output folder. If specified, the –output-file will be ignored and each sensor grid will be written into its own .json or .pts file within the folder.

-f, --output-file <output_file>

Optional file to output the JSON or CSV string of the sensor grids. By default this will be printed to stdout

Default

-

Arguments

MODEL_FILE

Required argument

from-face3ds

Generate a SensorGrid from a JSON array of Face3D objects.

Args:
face3d_file: Full path to a JSON file containing an array of Face3D objects
that will be used to generate the sensor grid. This could also be a
nested array (list of lists of Face3Ds), in which case a separate
SensorGrid will be computed for each sub-list.
honeybee-radiance grid from-face3ds [OPTIONS] FACE3D_FILE

Options

-n, --grid-name <grid_name>

Text string for the name of the SensorGrid, which will also be used to assign SensorGrid ID. This will be used to identify the object across a model and in the exported Radiance files so it is recommended that it be relatively unique. If unspecified, a random name will be generated.

-s, --grid-size <grid_size>

A number for the dimension of the mesh grid cells. This can include the units of the distance (eg. 1ft) or, if no units are provided, the value will be interpreted in the –units.

Default

0.5m

-o, --offset <offset>

A number for the distance at which the the sensor grid should be offset from the base geometry. This can include the units of the distance (eg. 3ft) or, if no units are provided, the value will be interpreted in the –units.

Default

0

-u, --units <units>

Text for the units system in which the Face3D geometry exists, which will be used to interpret the –grid-size and –offset inputs. Must be (Meters, Millimeters, Feet, Inches, Centimeters).

Default

Meters

--no-flip, -fl, --flip

Flag to note whether the mesh normals should be reversed from the direction of the face geometriesand the –offset move the sensors in the opposite direction from the face normals.

Default

True

--include-mesh, -xm, --exclude-mesh

Flag to note whether to include a Mesh3D object that aligns with the grid positions under the “mesh” property of each grid. Excluding the mesh can reduce size but will mean Radiance results cannot be visualized as colored meshes.

Default

True

--write-json, -pts, --write-pts

Flag to note whether output data collection should be in JSON format or the typical CSV-style format of the Radiance .pts files.

Default

True

--folder <folder>

Optional output folder. If specified, the –output-file will be ignored and each sensor grid will be written into its own .json or .pts file within the folder.

-f, --output-file <output_file>

Optional file to output the JSON or CSV string of the sensor grids. By default this will be printed to stdout

Default

-

Arguments

FACE3D_FILE

Required argument

from-rooms

Generate SensorGrids from the Room floors of a honeybee model.

Args:
model_file: Full path to a HBJSON or HBPkl Model file.
honeybee-radiance grid from-rooms [OPTIONS] MODEL_FILE

Options

-s, --grid-size <grid_size>

A number for the dimension of the mesh grid cells. This can include the units of the distance (eg. 1ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default

0.5m

-o, --offset <offset>

A number for the distance at which the the sensor grid should be offset from the floor. This can include the units of the distance (eg. 3ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default

0.8m

--include-mesh, -xm, --exclude-mesh

Flag to note whether to include a Mesh3D object that aligns with the grid positions under the “mesh” property of each grid. Excluding the mesh can reduce size but will mean Radiance results cannot be visualized as colored meshes.

Default

True

--keep-out, -out, --remove-out

Flag to note whether an extra check should be run to remove sensor points that lie outside the Room volume. Note that this can add significantly to the runtime and this check is not necessary in the case that all walls are vertical and all floors are horizontal.

Default

True

-w, --wall-offset <wall_offset>

A number for the distance at which sensors close to walls should be removed. This can include the units of the distance (eg. 3ft) or, if no units are provided, the value will be interpreted in the honeybee model units. Note that this option has no effect unless the value is more than half of the grid-size.

Default

0m

-r, --room <room>

Room identifier to specify the room for which sensor grids should be generated. You can pass multiple rooms (each preceded by -r). By default, all rooms get sensor grids.

--write-json, -pts, --write-pts

Flag to note whether output data collection should be in JSON format or the typical CSV-style format of the Radiance .pts files.

Default

True

--folder <folder>

Optional output folder. If specified, the –output-file will be ignored and each sensor grid will be written into its own .json or .pts file within the folder.

-f, --output-file <output_file>

Optional file to output the JSON or CSV string of the sensor grids. By default this will be printed to stdout

Default

-

Arguments

MODEL_FILE

Required argument

from-rooms-radial

Generate SensorGrids of radial directions around positions from room floors.

Args:
model_file: Full path to a HBJSON or HBPkl Model file.
honeybee-radiance grid from-rooms-radial [OPTIONS] MODEL_FILE

Options

-s, --grid-size <grid_size>

A number for the dimension of the radial grid. This can include the units of the distance (eg. 1ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default

0.5m

-o, --offset <offset>

A number for the distance at which the the sensor grid should be offset from the floor. This can include the units of the distance (eg. 3ft) or, if no units are provided, the value will be interpreted in the honeybee model units.

Default

1.2m

--include-mesh, -xm, --exclude-mesh

Flag to note whether to include a Mesh3D object that aligns with the grid positions under the “mesh” property of each grid. Excluding the mesh can reduce size but will mean Radiance results cannot be visualized as colored meshes.

Default

True

--keep-out, -out, --remove-out

Flag to note whether an extra check should be run to remove sensor points that lie outside the Room volume. Note that this can add significantly to the runtime and this check is not necessary in the case that all walls are vertical and all floors are horizontal.

Default

True

-w, --wall-offset <wall_offset>

A number for the distance at which sensors close to walls should be removed. This can include the units of the distance (eg. 3ft) or, if no units are provided, the value will be interpreted in the honeybee model units. Note that this option has no effect unless the value is more than half of the grid-size.

Default

0m

-d, --dir-count <dir_count>

A positive integer for the number of radial directions to be generated around each position.

Default

8

-v, --start-vector <start_vector>

An optional list of three values (separated by spaces) 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

-m, --mesh-radius <mesh_radius>

An optional number to override the radius of the meshes generated around each sensor. If unspecified, it will be equal to 45 percent of the grid-size. Set to zero to ensure no mesh is added to the resulting sensor grids.

-r, --room <room>

Room identifier to specify the room for which sensor grids should be generated. You can pass multiple rooms (each preceded by -r). By default, all rooms get sensor grids.

--write-json, -pts, --write-pts

Flag to note whether output data collection should be in JSON format or the typical CSV-style format of the Radiance .pts files.

Default

True

--folder <folder>

Optional output folder. If specified, the –output-file will be ignored and each sensor grid will be written into its own .json or .pts file within the folder.

-f, --output-file <output_file>

Optional file to output the JSON or CSV string of the sensor grids. By default this will be printed to stdout

Default

-

Arguments

MODEL_FILE

Required argument

merge

Merge several radiance files into a single file.

This command removes headers from file if it exist.

Args:
input_folder: Input folder.
base_name: File base name. All of the files must start with base name and
continue with _ and an integer values.
extension: File extension. [Default: .pts]
honeybee-radiance grid merge [OPTIONS] INPUT_FOLDER BASE_NAME [EXTENSION]

Options

--folder <folder>

Optional output folder.

Default

.

--name <name>

Optional output filename. Default is base-name.

Arguments

INPUT_FOLDER

Required argument

BASE_NAME

Required argument

EXTENSION

Optional argument

merge-folder

Restructure files in a distributed folder.

Args:
input_folder: Path to input folder.
output_folder: Path to the new restructured folder
extension: Extension of the files to collect data from. It will be pts for
sensor files. Another common extension is ill for the results of daylight
studies.
honeybee-radiance grid merge-folder [OPTIONS] INPUT_FOLDER OUTPUT_FOLDER
                                    EXTENSION

Options

-di, --dist-info <dist_info>

An optional input for distribution information to put the grids back together . Alternatively, the command will look for a _redist_info.json file inside the folder.

Arguments

INPUT_FOLDER

Required argument

OUTPUT_FOLDER

Required argument

EXTENSION

Required argument

mirror

Mirror a honeybee Model’s SensorGrids and format them for thermal mapping.

This involves setting the direction of every sensor to point up (0, 0, 1) and then adding a mirrored sensor grid with the same sensor positions that all point downward. In thermal mapping workflows, the upward-pointing grids can be used to account for direct and diffuse shortwave irradiance while the downward pointing grids account for ground-reflected shortwave irradiance.

Args:
model_json: Full path to a Model JSON file.
honeybee-radiance grid mirror [OPTIONS] GRID_FILE

Options

-v, --vector <vector>

An optional list of three values (separated by spaces) to standardize the direction of all rays in the output files. For example, inputting “0 0 1” will ensure that the output sensor files all have vectors pointing up in the base file and down in the mirrored file. If unspecified, the direction of sensors in the input file will be used.

-n, --name <name>

File name, which will be incorporated into both the base grid and the mirrored grid.

-s, --suffix <suffix>

Text for the suffix to be applied to the mirrored grid file.

Default

ref

-f, --folder <folder>

Output folder into which the base grid and mirrored grid files will be written.

-log, --log-file <log_file>

Optional log file to output the list of generated radiant enclosure JSONs. By default this will be printed to stdout.

Arguments

GRID_FILE

Required argument

split

Split a radiance grid file into smaller grids based on maximum sensor count.

Args:
grid-file: Full path to input sensor grid file.
count: Maximum number of sensors in new files. The number will be rounded to
closest round number for each file. For example if the input file has 21
sensors and input count is set to 5 this command will generate 4 files where
the first three files will have 5 sensors and the last file will have 6.
honeybee-radiance grid split [OPTIONS] GRID_FILE COUNT

Options

--folder <folder>

Output folder.

Default

.

--log-file <log_file>

Optional log file to output the name of the newly created grids. By default the list will be printed out to stdout

Arguments

GRID_FILE

Required argument

COUNT

Required argument

split-folder

Create new sensor grids folder with evenly distribute sensors.

This function creates a new folder with evenly distributed sensor grids. The folder will include a _dist_info.json file which has the information to recreate the original input files from this folder and the results generated based on the grids in this folder.

_dist_info.json file includes an array of JSON objects. Each object has the id or the original file and the distribution information. The distribution information includes the id of the new files that the sensors has been distributed to and the start and end line in the target file.

This file is being used to restructure the data that is generated based on the newly created sensor grids.

[
  {
    "id": "room_1",
    "dist_info": [
      {"id": 0, "st_ln": 0, "end_ln": 175},
      {"id": 1, "st_ln": 0, "end_ln": 21}
    ]
  },
  {
    "id": "room_2",
    "dist_info": [
      {"id": 1, "st_ln": 22, "end_ln": 135}
    ]
  }
]
Args:
input_folder: Input sensor grids folder.
output_folder: A new folder to write the newly created files.
grid_count: Number of output sensor grids to be created. This number
is usually equivalent to the number of processes that will be used to run
the simulations in parallel.
extension: Extension of the files to split. The default is pts for
sensor files. Another common extension is csv for data aligned with
the sensor grids.
honeybee-radiance grid split-folder [OPTIONS] INPUT_FOLDER OUTPUT_FOLDER
                                    GRID_COUNT [EXTENSION]

Options

-d, --grid-divisor <grid_divisor>

An optional integer to be divided by the grid-count to yield a final number of grids to generate. This is useful in workflows where the grid-count is being interpreted as a cpu-count but there are multiple processors acting on a single grid. To ignore this limitation set the value to 1. Default: 1.

-msc, --min-sensor-count <min_sensor_count>

Minimum number of sensors in each output grid. Use this number to ensure the number of sensors in output grids never gets very small. This input will override the input grid-count when specified. To ignore this limitation, set the value to 1. Default: 1.

--grid-info-file <grid_info_file>

Optional input JSON file containing information about the sensor grids to be split. If unspecified, it will be assumed that this JSON already exists in the input-folder with the name _info.json

Arguments

INPUT_FOLDER

Required argument

OUTPUT_FOLDER

Required argument

GRID_COUNT

Required argument

EXTENSION

Optional argument