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¶

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¶

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¶

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>¶

Default:: '1.2m'

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

Default:: True

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

Default:: True

-w, --wall-offset <wall_offset>¶

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