honeybee_vtk.camera module

A VTK camera object.

class honeybee_vtk.camera.Camera(identifier: str = 'camera', position: Tuple[float, float, float] = (0, 0, 100), direction: Tuple[float, float, float] = (0, 0, - 1), up_vector: Tuple[float, float, float] = (0, 1, 0), view_angle: int = 60, projection: str = 'v', reset_camera: bool = True, focal_point: Optional[Tuple[float, float, float]] = None, clipping_range: Optional[Tuple[float, float]] = None, parallel_scale: Optional[int] = None)[source]

Bases: honeybee_radiance.view.View

Create a vtk camera object.

This object inherits from the Honeybee_radiance.View object. https://www.ladybug.tools/honeybee-radiance/docs/honeybee_radiance.view.html

Parameters

  • identifier – A unique name for the camera. Defaults to ‘camera’.

  • position – x, y, z coordinates of the camera in a 3D space. Defaults to (0, 0, 100) which puts the camera 100 meters off of the XY plane (ground).

  • direction – x, y, and z components of a vector that represents the view direction (aim) of the camera. Defaults to (0, 0, -1). Which means the camera will look towards the XY plane (ground).

  • up_vector – x, y, and z component of the vector that represents where the top of the camera is. Defaults to (0, 1, 0).

  • view_angle – The angular hight of the camera view in degrees. You can think of this as the vertical view angle. Defaults to 60

  • projection – Choose between a perspective and parallel view type. ‘v’ will set the perspective view and ‘l’ will set the parallel view. Defaults to ‘v’.

  • reset_camera – A boolean that indicates whether the camera should be reset. Resetting the camera is helpful when you want to capture an image of a model from outside the model. This will make sure that the camera is far away from the model and the whole model is captured. This should be set to false in case of the intention is to take snapshots inside the model. A use case is taking the snapshots of the grids in the model. Defaults to True.

  • focal_point – x, y, and z coordinates of the point where the camera is looking at. Defaults to None which means the camera will look towards the XY plane (ground).

  • clipping_range – A range of two numbers that define the near plane and the far plane respectively. Both of these planes are perpendicular to the camera direction and are effective only in when the view type is parallel. The distance from the camera to the near plane is the closest distance that an object can be to the camera and still remain in the view. The distance from the camera to the far plane is the farthest distance that an object can be from the camera and still remain in the view. Defaults to None.

  • parallel_scale – Set the parallel scale for the camera. Note, that this parameters works as an inverse scale. So larger numbers produce smaller images.This can be thought of as the zoom in and zoom out control. This parameter is effective only when the view type is parallel. Defaults to None.

ToString()

Overwrite .NET ToString.

classmethod aerial_cameras(bounds: List[ladybug_geometry.geometry3d.pointvector.Point3D], centroid: ladybug_geometry.geometry3d.pointvector.Point3D) → List[T][source]

Get four aerial cameras.

Parameters

  • bounds – A list of Point3D objects representing bounds of the actors in the scene.

  • centroid – A Point3D object representing the centroid of the actors.

Returns

A list of Camera objects.

dimension(x_res=None, y_res=None)

Get dimensions for this view as ‘-x %d -y %d [-ld-]’.

This method is same as vwrays -d. Default values for x_res and y_res are set to match Radiance defaults.

dimension_x_y(x_res=None, y_res=None)

Get dimensions for this view as x, y.

Default values for x_res and y_res are set to match Radiance defaults.

duplicate()

Get a copy of this object.

classmethod from_dict(view_dict)

Create a view from a dictionary in the following format.

{
'type': 'View',
'identifier': str,  # View identifier
"display_name": str,  # View display name
'position': [],  # list with position value
'direction': [],  # list with direction value
'up_vector': [],  # list with up_vector value
'h_size': number,  # h_size.value
'v_size': number,  # v_size value
'shift': number,  # shift value
'lift': number,  # lift value
'view_type': number,  # view_type value
'fore_clip': number,  # fore_clip value
'aft_clip': number,  # aft_clip value
'room_identifier': str,  # optional room identifier
'light_path':  []  # optional list of lists for light path
}
classmethod from_file(file_path, identifier=None)

Create view from a view file.

Parameters

  • file_path – Full path to view file.

  • identifier – Optional ext string for a unique View 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, this will be set to file name. (Default: None)

classmethod from_grid(grid, identifier='from_grid')

Create view from a grid of views. Generally the grid argument should be the views generated by the grid method. :param grid: A list of subviews. If only a single view is given, this view will be

returned. The views can be either class instances of View, strings or .unf files. If strings are used, the views will be created by the from_string method. If .unf files are used, the views will be created by the from_string method using the view found in the Radiance header.

Parameters

identifier – Text string for a unique View 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, this will be set to ‘from_grid’. (Default: ‘from_grid’)

classmethod from_string(identifier, view_string)

Create a view object from a string.

This method is similar to from_string method for radiance parameters with the difference that all the parameters that are not related to view will be ignored.

classmethod from_view(view: honeybee_radiance.view.View) → T[source]

Create a Camera object from a radiance view.

Parameters

view – A radiance view

Returns

A Camera object.

classmethod from_view_file(file_path: str) → T[source]

Create a Camera object from a radiance view file.

Parameters

file_path – A valid path to a radiance view file with .vf extension.

Returns

A Camera object.

grid(x_div_count=1, y_div_count=1)

Break-down the view into a grid of views based on x and y grid count.

Views will be returned row by row from right to left.

Parameters

  • x_div_count – Set number of divisions in x direction (Default: 1).

  • y_div_count – Set number of divisions in y direction (Default: 1).

Returns

A tuple of views. Views are sorted row by row from right to left.

info_dict(model=None)

Get a dictionary with information about the View.

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 view.

Parameters

model – A honeybee Model object which will be used to identify the aperture groups that will be run with this view. Default: None.

move(moving_vec)

Move this view along a vector.

Parameters

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

reflect(plane)

Reflect this view across a plane.

Parameters

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

rotate(angle, axis=None, origin=None)

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

Parameters

  • angle – An angle for rotation in degrees.

  • axis – Rotation axis as a Vector3D. If None, self.up_vector will be used. (Default: None).

  • origin – A ladybug_geometry Point3D for the origin around which the object will be rotated. If None, self.position is used. (Default: None).

rotate_xy(angle, origin=None)

Rotate this view counterclockwise in the world XY plane by a certain angle.

Parameters

  • angle – An angle in degrees.

  • origin – A ladybug_geometry Point3D for the origin around which the object will be rotated. If None, self.position is used. (Default: None).

scale(factor, origin=None)

Scale this view 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).

standardize_fisheye()

Automatically set view size to 180 degrees if the view type is a fisheye.

Alternatively it sets the view size to 360 degrees if both the view type is angular fisheye and either the horizontal or vertical view size is 360 degrees.

to_dict()

Translate view to a dictionary.

to_file(folder, file_name=None, mkdir=False)

Save view to a file.

Parameters

  • folder – Target folder.

  • 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).

Returns

Full path to newly created file.

to_radiance()

Return full Radiance definition as a string.

to_vtk() → vtkmodules.vtkRenderingCore.vtkCamera[source]

Get a vtk camera object

property aft_clip

View aft clip (-va) at a distance from the view point.

Set the view aft clipping plane at a distance of val from the view point. Like the view fore plane, it will be perpendicular to the view direction for perspective and parallel view types. For fisheye view types, the clipping plane is actually a clipping sphere, centered on the view point with radius val. Objects behind this imaginary surface will not be visible. A value of zero means no aft clipping, and is the only way to see infinitely distant objects such as the sky.

property direction

Set the view direction (-vd) vector to (x, y, z).

The length of this vector indicates the focal distance as needed by the pixel depth of field (-pd) in rpict. Default: (0, 0, 1)

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 fore_clip

View fore clip (-vo) at a distance from the view point.

The plane will be perpendicular to the view direction for perspective and parallel view types. For fisheye view types, the clipping plane is actually a clipping sphere, centered on the view point with radius val. Objects in front of this imaginary surface will not be visible. This may be useful for seeing through walls (to get a longer perspective from an exterior view point) or for incremental rendering. A value of zero implies no foreground clipping. A negative value produces some interesting effects, since it creates an inverted image for objects behind the viewpoint.

property full_identifier

Get full identifier for view.

For a view with group identifier it will be group_identifier/identifier

property group_identifier

Get or set text for the grid 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 view groups. For example floor_1/living_room create a view under living_room/floor_1 subfolder.

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

property h_size

Set the view horizontal size (-vh).

For a perspective projection (including fisheye views), this is the horizontal field of view (in degrees). For a parallel projection, this is the view width in world coordinates.

property identifier

Get or set a text string for a unique View identifier.

property is_fisheye

Check if the view type is one of the fisheye views.

property lift

Set the view lift (-vl) to a value.

This is the amount the actual image will be lifted up from the specified view.

property light_path

Get or set list of lists for the light path from the view 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 position

Set the view position (-vp) to (x, y, z).

This is the focal point of a perspective view or the center of a parallel projection. Default: (0, 0, 0)

property reset_camera

Get a boolean that indicates whether the camera should be reset.

property room_identifier

Get or set text for the Room identifier to which this View 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 view. If None, the view will be run with all aperture groups in the model.

property shift

Set the view shift (-vs).

This is the amount the actual image will be shifted to the right of the specified view. This option is useful for generating skewed perspectives or rendering an image a piece at a time. A value of 1 means that the rendered image starts just to the right of the normal view. A value of -1 would be to the left. Larger or fractional values are permitted as well.

property type

Set and get view type (-vt) to one of the choices below.

  • v - Perspective (v)

  • h - Hemispherical fisheye (h)

  • l - Parallel (l)

  • c - Cylindrical panorama (c)

  • a - Angular fisheye (a)

  • s - Planisphere [stereographic] projection (s)

property up_vector

Set and get the view up (-vu) vector (vertical direction) to (x, y, z)

Default: (0, 1, 0).

property v_size

Set the view vertical size (-vv).

For a perspective projection (including fisheye views), this is the horizontal field of view (in degrees). For a parallel projection, this is the view width in world coordinates.

property va

View aft clip as a string in radiance format.

property vd

View direction as a string in radiance format.

property vh

View horizontal size as a string in radiance format.

property vl

View lift as a string in radiance format.

property vo

View fore clip as a string in radiance format.

property vp

View point / position as a string in radiance format.

property vs

View shift as a string in radiance format.

property vt

View type as a string in radiance format.

property vu

View up as a string in radiance format.

property vv

View vertical size as a string in radiance format.