Facet

Facet class inherited by all facet classes

class opencsp.common.lib.csp.Facet.Facet(mirror: MirrorAbstract, name: str | None = None)

Bases: RayTraceable, VisualizeOrthorectifiedSlopeAbstract, OpticOrientationAbstract

Facet representation that contains a MirrorAbstract object.

__init__(mirror: MirrorAbstract, name: str | None = None) → Facet

Instantiates Facet class

Parameters:: mirror (MirrorAbstract) – Mirror object held inside Facet

draw(view: View3d, facet_style: RenderControlFacet | None = None, transform: TransformXYZ | None = None) → None

Draws facet mirror onto a View3d object.

Parameters:

viewView3d: A view 3d object that holds the figure.
mirror_stylesRenderControlMirror: Holds attibutes about the 3d graph.
transformTransformXYZ: 3d transform used to position points in the mirror’s base coordinate reference frame in space. If None, defaults to position points in the facet’s global coordinate reference frame.

get_2D_dimensions() → tuple[float, float]

Returns width and heightin facet’s child coordinate reference frame.

Returns:: Width: following (+)x infinity in the (-) direction for x_max(right) - following (-x) infinity in the (+) direction for x_min(left). Height: following (+)y infinity in the (-) direction for y_max(top) - following (-y) infinity in the (+) direction for y_min(bottom). Facet’s child coordinate reference frame.
Return type:: tuple[float, float]

most_basic_ray_tracable_objects() → list[RayTraceable]: Return the list of the smallest Ray Traceable that makes up the larger object.

orthorectified_slope_array(x_vec: ndarray, y_vec: ndarray) → ndarray

Returns X and Y surface slopes in ndarray format given X and Y sampling axes in the facet’s child coordinate reference frame.

Parameters:: x_vec/y_vec (ndarray) – X and Y grid sampling vectors in facet’s child coordinate reference frame
Returns:: X and Y slope images of shape: (2, y_vec.size, x_vec.size), in the facet’s child coordinate reference system.
Return type:: ndarray

survey_of_points(resolution: Resolution) → tuple[Pxyz, Vxyz]

Returns a set of points sampled from inside the optic region in the optic’s global coordinate reference frame.

Parameters:

resolution (Resolution) – container of the list of points to survey over. If the Resolution is unresolved then it will be resolved in the bounding box of self.

Returns:

A tuple of the points (Pxyz) and normals at the respective points (Vxyz) in
the object’s global coordinate reference frame.

property axis_aligned_bounding_box: tuple[float, float, float, float]

Returns bounding box aligned to XY axes in facet’s child coordinate reference frame.

Returns:: Left, right, bottom, top. Facet’s child coordinate reference frame.
Return type:: tuple[float, float, float, float]

property children: list[OpticOrientationAbstract]: Returns the children of this instance of OpticOrientationAbstract decendent.

property transform_mirror_to_self: TransformXYZ: Returns the mirror to facet 3d transform

Rigid ensemble of facets

class opencsp.common.lib.csp.FacetEnsemble.FacetEnsemble(facets: list[Facet])

Bases: RayTraceable, VisualizeOrthorectifiedSlopeAbstract, OpticOrientationAbstract

Ensemble of facets that holds Facet objects.

__init__(facets: list[Facet])

Instantiates FacetEnsemble class

Parameters:: facets (list[Facet]) – List of located facets to place in facet ensemble.

draw(view: View3d, facet_ensemble_style: RenderControlFacetEnsemble | None = None, transform: TransformXYZ | None = None) → None

Draws facet ensemble onto a View3d object.

Parameters:

viewView3d: A View3d object that holds the figure.
facet_stylesRenderControlFacetEnsemble: Holds information on how to draw each facet, inclusing information on how to draw specific facets.
transformTransformXYZ | None: List of 3d transforms for each facet in ensemble. Used to position points in the FacetEnsemble’s base coordinate reference frame in space. If None, defaults to position points in the ensemble’s global coordinate reference frame.

lookup_facet(facet_name: str) → Facet: Returns the first Facet in the FacetEnsemble that matches the given name. If there are no facets that match the given name it throws a KeyError.

orthorectified_slope_array(x_vec: ndarray, y_vec: ndarray) → ndarray

set_facet_cantings(canting_rotations: list[Rotation])

Set the canting rotations of the facets relative to the ensemble. This function updates the canting rotations of the facets in the ensemble. It will remove any previously set facet positional transformations.

Parameters:: canting_rotations (list[Rotation]) – A list of rotation objects to set for each facet. The length of this list must match the number of facets in the ensemble.
Raises:: ValueError – If the length of canting_rotations does not match the number of facets in the ensemble.

Notes

This method modifies the internal transformation of each facet based on the provided canting rotations and their corresponding positions.

set_facet_positions(positions: Pxyz)

Set the positions of the facets relative to one another. This function updates the positions of the facets in the ensemble. It will remove any previously set facet canting rotations.

Parameters:: positions (Pxyz) – A sequence of positions to set for each facet. The length of this sequence must match the number of facets in the ensemble.
Raises:: ValueError – If the length of positions does not match the number of facets in the ensemble.

Notes

This method modifies the internal transformation of each facet based on the provided positions.

set_facet_transform_list(transformations: list[TransformXYZ]): Combines the set_facet_positions and set_facet_cantings functions into a single action.

survey_of_points(resolution: Resolution) → tuple[Pxyz, Vxyz]

Returns a set of points sampled from inside the optic region in the optic’s global coordinate reference frame.

Parameters:

resolution (Resolution) – container of the list of points to survey over. If the Resolution is unresolved then it will be resolved in the bounding box of self.

Returns:

A tuple of the points (Pxyz) and normals at the respective points (Vxyz) in
the object’s global coordinate reference frame.

property axis_aligned_bounding_box: tuple[float, float, float, float]

Returns bounding box aligned to XY axes in ensemble’s child coordinate reference frame.

Returns:: Left, right, bottom, top. Ensemble’s child coordinate reference frame.
Return type:: tuple[float, float, float, float]

property children: Returns the children of this instance of OpticOrientationAbstract decendent.

property facet_positions: Pxyz: The locations of the facets relative to the FacetEnsemble origin.

property transform_mirror_to_self: List of transforms from Mirror to self

Heliostat

Heliostat Class

class opencsp.common.lib.csp.HeliostatAbstract.HeliostatAbstract(facet_ensemble: FacetEnsemble, name: str | None = None)

Bases: RayTraceable, OpticOrientationAbstract, ABC

Heliostat representation.

Parameters:: facet_ensemble (FacetEnsemble) – List of facets, in order from top-left to bottom-right (row major order). The facet names should be their position in the list (1-indexed).

__init__(facet_ensemble: FacetEnsemble, name: str | None = None) → None

draw(view: View3d, heliostat_style: RenderControlHeliostat | None = None, transform: TransformXYZ | None = None)

Draws heliostat onto a View3d object.

Parameters:

viewView3d: A View3d object that holds the figure.
heliostat_styleRenderControlHeliostat: Holds information on how to draw the heliostat and the objects that make up the heliostat.
transformTransformXYZ | None: List of 3d transforms for each facet in ensemble. Used to position points in the Heliostat’s base coordinate reference frame in space. If None, defaults to position points in the heliostat’s global coordinate reference frame.

abstract from_pointing_vector_to_configuration(pointing_vector: Vxyz) → HeliostatConfiguration

Gets the configuration for the heliostat that would move the heliostat so it is facing the given direction.

Parameter

pointing_vector: Vxyz: A vector that represents a direction the heliostat is pointing.

returns:: The configuration that contains values that would move the heliostat to point on the direction of pointing_vector if they were used as arguments in set_orientation.
rtype:: tuple

lookup_facet(facet_name: str): Returns the first Facet in the Helisotat’s FacetEnsemble that matches the given name. If there are no facets that match the given name it throws a KeyError.

abstract movement_transform(config: HeliostatConfiguration) → TransformXYZ

Instantiable classes that inheret HeliostatAbstract are required to have a functiont that takes in input and returns a TransformationXYZ object. This function can be called by another function that better describes the motion, but this one needs to exist to make sure the child class is a proper heliostat.

Parameters:: config (HeliostatConfiguration) – The arguments required by the Heliostat instance. Should be the same type as self.current_configuration.
Returns:: The transformation of the heliostat given the input *args.
Return type:: TransformXYZ

Example

# override movement_transform in HeliostatAbstract
def movement_transform(self, az_angle: float, el_angle: float):
    '''possible movement_transform for an oversimplified
    azimuth and elevation based heliostat.'''
    az_rotation = Rotation.from_euler('z', az_angle)
    transform_az = TransformXYZ.from_R(az_rotation)
    el_rotation = # rotate about the proper vector
    transform_el = TransformXYZ.from_R(el_rotation)
    composite_transform = transform_el * transform_az
    return composite_transform

set_canting_from_equation(func: FunctionXYContinuous) → None

Uses an equation to set the canting of the facets on the heliostat.

Parameters:

func: FunctionXYContinuous: The function that is used to set the canting angles. The function is of the form z = f(x, y) and the surface normal at (x0, y0) is the direction that a facet at (x0, y0) will point.

set_facet_cantings(canting_rotations: list[Rotation])

set_facet_positions(positions: Pxyz)

set_orientation(config: HeliostatConfiguration) → None: Uses the movement_transform(self, *args) function to set the _self_to_parent_transform transformation of the FacetEnsemble in heliostat.

set_orientation_from_pointing_vector(pointing_vector: Vxyz) → None: Sets the pointing direction of the Heliostat to be the direction given. Note that this function depends on the individual implmentation of each heliostat.

set_tracking_configuration(aimpoint: Pxyz, location_lon_lat: Iterable, when_ymdhmsz: tuple): Orients the facet ensemble to point at the aimpoint given a location and time.

survey_of_points(resolution: Resolution) → tuple[Pxyz, Vxyz]

Returns a set of points sampled from inside the optic region in the optic’s global coordinate reference frame.

Parameters:

resolution (Resolution) – container of the list of points to survey over. If the Resolution is unresolved then it will be resolved in the bounding box of self.

Returns:

A tuple of the points (Pxyz) and normals at the respective points (Vxyz) in
the object’s global coordinate reference frame.

property axis_aligned_bounding_box: tuple[float, float, float, float]

Returns bounding box aligned to XY axes in heliostat’s coordinate reference frame.

Returns:: Left, right, bottom, top. Heliostat’s coordinate reference frame.
Return type:: tuple[float, float, float, float]

property children: Returns the children of this instance of OpticOrientationAbstract decendent.

abstract property current_configuration: HeliostatConfiguration

A tuple of the values that define the current state of the heliostat.

Must adhere to the following property: `python heliostat: HeliostatAbstract # in some state current = helistat.current_configuration heliostat.set_orientation(current) # this should not change the heliostat `

class opencsp.common.lib.csp.HeliostatAzEl.HeliostatAzEl(facet_ensemble: FacetEnsemble, name: str | None = None)

Bases: HeliostatAbstract

Child class of HeliostatAbstract. HeliostatAzEl instances have motion characterized by a motor that rotates the heliostat in the azumuth direction (an angle measured clockwise from North in UNE cooridinates or from y in XYZ coordinates) and a motor that rotates up from the East-North plane (XY plane).

__init__(facet_ensemble: FacetEnsemble, name: str | None = None) → None

classmethod from_attributes(number_of_facets: int, facet_positions: Pxyz, mirror_template: MirrorAbstract, name: str | None = None, facet_names: list[str] | None = None, pivot: float = 0) → HeliostatAzEl: Creates a Heliostat of identical mirrors as given by the facet_template. Positions the facets as given by the attributes

classmethod from_csv_files(heliostat_name: str, heliostat_attributes_csv: str, facet_attributes_csv: str, mirror_template: MirrorAbstract) → tuple[HeliostatAzEl, Pxyz]

returns the heliostat that is requested based on the given information

Paramters

helisotat_name: str: the name of the heliostat as given in the csv file
heliostat_attribute_csv: str: filepath to the csv file that contains information about the desired heliostat.
facet_attricute_csv: str: filepath ot the csv file that describes how the facets in the desired heliost will be positoned and named.
mirror_template: MirrorAbstract: the desired heliostat will have uniform mirrors, this is the teplate that all mirrors will be based on

returns:

tuple[HeliostatAzEl, Pxyz]
HeliostatAzEl – the helistat that is defined by the csv files
Pxyz – the position of the heliostat as given by the heliostat_attributes_csv

from_pointing_vector_to_configuration(pointing_vector: Vxyz) → HeliostatConfiguration

Gets the configuration for the heliostat that would move the heliostat so it is facing the given direction.

Parameter

pointing_vector: Vxyz: A vector that represents a direction the heliostat is pointing.

returns:: The configuration that contains values that would move the heliostat to point on the direction of pointing_vector if they were used as arguments in set_orientation.
rtype:: tuple

movement_transform(config: HeliostatConfiguration)

Instantiable classes that inheret HeliostatAbstract are required to have a functiont that takes in input and returns a TransformationXYZ object. This function can be called by another function that better describes the motion, but this one needs to exist to make sure the child class is a proper heliostat.

Parameters:: config (HeliostatConfiguration) – The arguments required by the Heliostat instance. Should be the same type as self.current_configuration.
Returns:: The transformation of the heliostat given the input *args.
Return type:: TransformXYZ

Example

# override movement_transform in HeliostatAbstract
def movement_transform(self, az_angle: float, el_angle: float):
    '''possible movement_transform for an oversimplified
    azimuth and elevation based heliostat.'''
    az_rotation = Rotation.from_euler('z', az_angle)
    transform_az = TransformXYZ.from_R(az_rotation)
    el_rotation = # rotate about the proper vector
    transform_el = TransformXYZ.from_R(el_rotation)
    composite_transform = transform_el * transform_az
    return composite_transform

set_orientation_from_az_el(az_angle: float, el_angle: float)

transform_from_az_el(az_angle: float, el_angle: float): movement_transform for an azimuth and elevation based heliostat.

property current_configuration: HeliostatConfiguration

A tuple of the values that define the current state of the heliostat.

Must adhere to the following property: `python heliostat: HeliostatAbstract # in some state current = helistat.current_configuration heliostat.set_orientation(current) # this should not change the heliostat `

property default_direction

property pivot

class opencsp.common.lib.csp.HeliostatConfiguration.HeliostatConfiguration(heliostat_type: str, az: float | None = None, el: float | None = None)

Bases: object

Container for the variables defining the heliostat configuration.

This class allows the user to define a heliostat configuration by specifying the type of heliostat and its associated parameters. Currently, only the ‘az-el’ type is supported, which requires azimuth and elevation angles.

Parameters:

heliostat_type (str) – The type of heliostat configuration. Must be one of the valid heliostat types.
az (float, optional) – The azimuth angle in radians (required for ‘az-el’ type).
el (float, optional) – The elevation angle in radians (required for ‘az-el’ type).

Raises:

ValueError – If the provided heliostat type is invalid or if az and el are not provided for the ‘az-el’ type.

__init__(heliostat_type: str, az: float | None = None, el: float | None = None) → None

Initializes a HeliostatConfiguration object with the specified type and angles.

Parameters:

heliostat_type (str) – The type of heliostat configuration.
az (float, optional) – The azimuth angle in radians (default is None).
el (float, optional) – The elevation angle in radians (default is None).

get_values()

Retrieves the azimuth and elevation values for the heliostat configuration.

Returns:: A tuple containing the azimuth and elevation angles in radians.
Return type:: tuple
Raises:: ValueError – If the heliostat type is invalid.

opencsp.common.lib.csp.HeliostatConfiguration.NSTTF_stow() → HeliostatConfiguration

Creates a HeliostatConfiguration for the NSTTF stow position.

Returns:: A HeliostatConfiguration object with azimuth set to 270 radians and elevation set to -85 radians.
Return type:: HeliostatConfiguration

opencsp.common.lib.csp.HeliostatConfiguration.face_east() → HeliostatConfiguration

Creates a HeliostatConfiguration for a heliostat facing east.

Returns:: A HeliostatConfiguration object with azimuth set to 90 radians and elevation set to 0 radians.
Return type:: HeliostatConfiguration

opencsp.common.lib.csp.HeliostatConfiguration.face_north() → HeliostatConfiguration

Creates a HeliostatConfiguration for a heliostat facing north.

Returns:: A HeliostatConfiguration object with azimuth set to 0 radians and elevation set to 0 radians.
Return type:: HeliostatConfiguration

opencsp.common.lib.csp.HeliostatConfiguration.face_south() → HeliostatConfiguration

Creates a HeliostatConfiguration for a heliostat facing south.

Returns:: A HeliostatConfiguration object with azimuth set to 180 radians and elevation set to 0 radians.
Return type:: HeliostatConfiguration

opencsp.common.lib.csp.HeliostatConfiguration.face_up() → HeliostatConfiguration

Creates a HeliostatConfiguration for a heliostat facing directly up.

Returns:: A HeliostatConfiguration object with azimuth set to 180 radians and elevation set to 90 radians.
Return type:: HeliostatConfiguration

opencsp.common.lib.csp.HeliostatConfiguration.face_west() → HeliostatConfiguration

Creates a HeliostatConfiguration for a heliostat facing west.

Returns:: A HeliostatConfiguration object with azimuth set to 270 radians and elevation set to 0 radians.
Return type:: HeliostatConfiguration

opencsp.common.lib.csp.HeliostatConfiguration.heliostat_configuration_given_surface_normal_xyz(n_xyz) → HeliostatConfiguration

Creates a HeliostatConfiguration from a given surface normal vector.

This function converts the surface normal coordinates into azimuth and elevation angles.

Parameters:: n_xyz (array-like) – A 3-element array or list representing the surface normal vector in 3D space.
Returns:: A HeliostatConfiguration object with the calculated azimuth and elevation angles.
Return type:: HeliostatConfiguration

LightPath

class opencsp.common.lib.csp.LightPath.LightPath(points_list: Pxyz, init_direction: Uxyz, current_direction: Uxyz | None = None, color: tuple[float, float, float] | None = None, intensity: list[float] | None = None)

Bases: object

The LightPath will represent the path of a photon in a light beam. There are two ways to think about the photon for this class.

1. The photon originates at an unknown point, and only has an original known direction (init_direction [OldVxyz]) and then has bounce off a point(s) and now is continuing in the direction of current_direction.

2. The photon originated at the first point in the list of points it has passed through. In this case the init_direction sould be [0, 0, 0].

In either case, to represent a photon that no longer exists (i.e. hits a wall and did not reflect) simply set the current_dirrection to [0, 0, 0].

__init__(points_list: Pxyz, init_direction: Uxyz, current_direction: Uxyz | None = None, color: tuple[float, float, float] | None = None, intensity: list[float] | None = None) → None

Parameters:

(list[OldPxyz]) (points_list -- list of points that the light has passed through/reflected at)
tracking (init_direction -- the initial direction the light was traveling when we started) – the first point in the points_list then this should be np.array([0, 0, 0]) (OldUxyz)
at (if we assume the light started) – the first point in the points_list then this should be np.array([0, 0, 0]) (OldUxyz)
the (intensity -- the intesity at each part of the light's journey. if the light started going in) – no value is given. (OldUxyz)
(tuple[float (color -- 3-tuple for RGB color)
float
float])
the – direction v1, passed through [p1, p2, p3], and is currently going in the direction v2, then the intensity would be [i@v1, i_after_p1, i_after_p2 , i_after_p3 or i@v2]. (list[float])

add_step(point: Pxyz, new_direction: Uxyz, new_intensity: float | None = None)

draw(view: ~opencsp.common.lib.render.View3d.View3d, path_style: ~opencsp.common.lib.render_control.RenderControlLightPath.RenderControlLightPath = <opencsp.common.lib.render_control.RenderControlLightPath.RenderControlLightPath object>) → None

many_rays_from_many_vectors(many_init_directions: Vxyz, many_current_directions: Vxyz = []) → list[LightPath]: Creates a list of LightPaths from vectors If the many_points_lists is None then the function will infer that they are all just the current vectors and have no history.

class opencsp.common.lib.csp.LightPathEnsemble.LightPathEnsemble(lps: list[LightPath])

Bases: object

A container for managing a collection of light paths.

This class aggregates multiple LightPath objects, allowing for operations such as concatenation and direction management.

current_directions

The current directions of the light paths in the ensemble.

Type:: Vxyz

init_directions

The initial directions of the light paths in the ensemble.

Type:: Vxyz

points_lists

A list of point lists for each light path in the ensemble.

Type:: list[list[Pxyz]]

colors

A list of colors associated with each light path in the ensemble.

Type:: list

__init__(lps: list[LightPath]) → None

Initializes a LightPathEnsemble with the given light paths.

Parameters:: lps (list[LightPath]) – A list of LightPath objects to initialize the ensemble.

add_steps(points: Pxyz, new_current_directions: Uxyz)

Adds new steps to the light paths in the ensemble.

Parameters:

points (Pxyz) – A list of new points to append to each light path.
new_current_directions (Uxyz) – A list of new current directions corresponding to the new points.

Raises:

ValueError – If the number of points does not match the number of new directions or if the number of new steps does not match the number of light paths.

asLightPathList() → list[LightPath]

Converts the ensemble into a list of LightPath objects.

Returns:: A list of LightPath objects constructed from the ensemble’s data.
Return type:: list[LightPath]

concatenate(lpe1: LightPathEnsemble)

Concatenates another LightPathEnsemble and returns a new instance.

Parameters:: lpe1 (LightPathEnsemble) – The LightPathEnsemble to concatenate.
Returns:: A new LightPathEnsemble containing the concatenated data.
Return type:: LightPathEnsemble

concatenate_in_place(lpe1: LightPathEnsemble)

Concatenates another LightPathEnsemble into this one in place.

Parameters:: lpe1 (LightPathEnsemble) – The LightPathEnsemble to concatenate.
Returns:: The updated LightPathEnsemble after concatenation.
Return type:: LightPathEnsemble

classmethod from_parts(init_directions: Uxyz, points: list[Pxyz], curr_directions: Uxyz, colors=[])

Creates a LightPathEnsemble from its component parts.

Parameters:

init_directions (Uxyz) – The initial directions of the light paths.
points (list[Pxyz]) – A list of point lists for each light path.
curr_directions (Uxyz) – The current directions of the light paths.
colors (list, optional) – A list of colors associated with each light path (default is empty list).

Returns:

A new LightPathEnsemble object constructed from the provided parts.

Return type:

LightPathEnsemble

LightSource

class opencsp.common.lib.csp.LightSource.LightSource

Bases: ABC

interface for objects that can be light sources

abstract get_incident_rays(point: Pxyz) → list[LightPath]: Returns the rays originating from this light source incident to the point.

class opencsp.common.lib.csp.LightSourcePoint.LightSourcePoint(location_in_space: Pxyz)

Bases: LightSource

A class representing a point light source in 3D space.

This class defines a light source located at a specific point in space, characterized by its position and the ability to generate incident rays towards a specified point.

__init__(location_in_space: Pxyz) → None

Initializes a LightSourcePoint with the specified location in space.

Parameters:: location_in_space (Pxyz) – The position of the light source in 3D space.
Raises:: TypeError – If the input location_in_space is not a subclass of Vxyz.

get_incident_rays(point: Pxyz) → list[LightPath]

Generates a list of incident rays from the light source to a specified point.

Parameters:: point (Pxyz) – The target point in 3D space to which the incident rays are directed.
Returns:: A list of LightPath objects representing the incident rays from the light source to the specified point.
Return type:: list[LightPath]
Raises:: TypeError – If the input point is not a subclass of Vxyz.

class opencsp.common.lib.csp.LightSourceSun.LightSourceSun

Bases: LightSource

A class representing a point light source that simulates sunlight.

This class models the sun as a top-hat function in space, allowing for the generation of incident rays based on the sun’s position in the sky.

incident_rays

A list of LightPath objects representing the rays incident from the sun.

Type:: list[LightPath]

__init__() → None

Initializes a LightSourceSun object with an empty list of incident rays.

Parameters:: None

classmethod from_given_sun_position(sun_pointing: Uxyz, resolution: int, sun_dia: float = 0.009308, verbose=False) → LightSourceSun

Creates a LightSourceSun object initialized from a given sun pointing direction.

Represents the sun as a top-hat function in space.

Parameters:

sun_pointing (Uxyz) – The pointing direction of the sun.
resolution (int) – The number of points in each direction that will be sampled.
sun_dia (float, optional) – The angular diameter of the sun in radians (default is 0.009308).
verbose (bool, optional) – If True, prints updates during initialization (default is False).

Returns:

A LightSourceSun object initialized with the specified sun pointing direction.

Return type:

LightSourceSun

classmethod from_location_time(loc: tuple[float, float], time: datetime, resolution: int, sun_dia: float = 0.009308, verbose=False) → LightSourceSun

Creates a LightSourceSun object initialized from a given latitude/longitude and time.

Represents the sun as a top-hat function in space.

Parameters:

loc (tuple[float, float]) – The location of the scene in the form (latitude, longitude) in degrees, WGS84.
time (datetime.datetime) – A datetime object representing the time. Must have timezone set.
resolution (int) – The number of points in each direction that will be sampled.
sun_dia (float, optional) – The angular diameter of the sun in radians (default is 0.009308).
verbose (bool, optional) – If True, prints updates during initialization (default is False).

Returns:

A LightSourceSun object initialized based on the specified location and time.

Return type:

LightSourceSun

get_incident_rays(point: Pxyz) → list[LightPath]

Retrieves the incident rays from the light source.

Parameters:: point (Pxyz) – The point in space for which the incident rays are requested.
Returns:: A list of LightPath objects representing the incident rays.
Return type:: list[LightPath]

set_incident_rays(loc: tuple[float, float], time: tuple, resolution: int, sun_dia: float = 0.009308, verbose=False) → None

Defines the rays that will be used from this light source for ray tracing.

Sets them to self.incident_rays.

Parameters:

loc (tuple[float, float]) – A tuple representing the location of the scene that will see the sun rays in the form (longitude, latitude).
time (tuple) – A tuple in the ymdhmsz convention, representing (year, month, day, hour, minute, second, time zone).
resolution (int) – The number of points in each direction that will be sampled.
sun_dia (float, optional) – The angular diameter of the sun in radians (default is 0.009308).
verbose (bool, optional) – If True, prints updates on how many rays have been generated to the console (default is False).

Raises:

DeprecationWarning – If this method is called, indicating it is deprecated.

Mirror

Abstract mirror representing a single reflective surface

class opencsp.common.lib.csp.MirrorAbstract.MirrorAbstract(shape: RegionXY)

Bases: RayTraceable, VisualizeOrthorectifiedSlopeAbstract, OpticOrientationAbstract

Abstract class inherited by all mirror classes

__init__(shape: RegionXY) → None

draw(view: View3d, mirror_style: RenderControlMirror | None = None, transform: TransformXYZ | None = None) → None

Draws a mirror onto a View3d object.

Parameters:

viewView3d: A view 3d object that holds the figure.
mirror_stylesRenderControlMirror: Holds attibutes about the 3d graph.
transformTransformXYZ: 3d transform used to position points in the mirror’s base coordinate reference frame in space. If None, defaults to position points in the mirror’s parent coordinate reference frame.

in_bounds(p: Pxy) → ndarray[bool]

Determines what points are valid points on the mirror. Input points are in the optic’s base coordinate reference frame.

Parameters:: p (Pxy) – The set of points in the top-down view of the mirror in the mirror’s base coordinate reference frame
Returns:: 1d ndarray with size equal to the length of the input p. Elements are booleans. True if point is within optic region, false otherwise.
Return type:: np.ndarray[bool]

location_at(p: Pxy) → Pxyz

Given an XY sample point in the mirror base reference frame, returns the XYZ point on the mirror’s surface in the mirror’s base reference frame.

Parameters:: p (Pxy) – Sample point in mirror’s base coordinate reference frame.
Returns:: XYZ sample points on surface in mirror’s base coordinate reference frame
Return type:: Pxyz

location_in_space(p: Pxy) → Pxyz

Given an XY sample point in the mirror’s base reference frame, returns the XYZ point on the mirror’s surface in the mirror’s parent reference frame.

Parameters:

pPxy: Sample point in mirror’s base coordinate reference frame.

Returns:

Pxyz: XYZ sample points on surface in mirror’s parent coordinate reference frame

most_basic_ray_tracable_objects() → list[RayTraceable]: Return the list of the smallest Ray Traceable that makes up the larger object.

orthorectified_slope_array(x_vec: ndarray, y_vec: ndarray) → ndarray

Returns X and Y surface slopes in ndarray format given X and Y sampling axes in the mirror’s base coordinate reference frame.

Parameters:: x_vec/y_vec (ndarray) – X and Y grid sampling vectors in mirror’s base coordinate reference frame
Returns:: X and Y slope images of shape: (2, y_vec.size, x_vec.size), in the mirror’s base coordinate reference system.
Return type:: ndarray

point_and_normal_in_space(p: Pxy) → tuple[Pxyz, Vxyz]

Given an XY sample point in the mirror’s base reference frame, return the XYZ point on the mirror’s surface and the surface normal in the mirror’s parent reference frame.

Parameters:: p (Pxy) – Sample point in mirror’s base coordinate reference frame.
Returns:: Surface points and normal vectors in mirror’s parent coordinate reference frame.
Return type:: tuple[Pxyz, Vxyz]

abstract surface_displacement_at(p: Pxy) → ndarray[float]

Given an XY sample point in the mirror’s base reference frame, returns the z displacement at the given location in the mirror’s base coordinate reference frame.

Parameters:: p (Pxy) – Sample point in mirror’s base coordinate reference frame.
Returns:: Distance from the z=0 plane in mirror’s base coordinate reference frame.
Return type:: ndarray[float]

abstract surface_norm_at(p: Pxy) → Vxyz

Given an XY sample point in the mirror’s base reference frame, returns the surface normal at the given location in the mirror’s base coordinate reference frame.

Parameters:: p (Pxy) – Sample point in mirror’s base coordinate reference frame.
Returns:: Normal vector of length len(p) in mirror’s base coordinate reference frame.
Return type:: Vxyz

surface_normal_in_space(p: Pxy) → Vxyz

Given an XY sample point in the mirror’s base reference frame, returns the surface normal at the given location in the mirror’s parent coordinate reference frame.

Parameters:

pPxy: Sample point in mirror’s base coordinate reference frame.

Returns:

Vxyz: Normal vector of length len(p) in mirror’s parent coordinate reference frame.

survey_of_points(resolution: Resolution) → tuple[Pxyz, Vxyz]

Returns a set of points sampled from inside the optic region in the optic’s global coordinate reference frame.

Parameters:

resolution (Resolution) – container of the list of points to survey over. If the Resolution is unresolved then it will be resolved in the bounding box of self.

Returns:

A tuple of the points (Pxyz) and normals at the respective points (Vxyz) in
the object’s global coordinate reference frame.

survey_of_points_local(resolution: int, resolution_type: str = 'pixelX', random_seed: int | None = None) → tuple[Pxyz, Vxyz]

Returns a set of points sampled from inside the optic region in the mirror’s base coordinate reference frame.

See self.survey_of_points() for input descriptions

Returns:

A tuple of the points (Pxyz) and normals at the respective points (Vxyz) in
the object’s base coordinate reference frame.

property axis_aligned_bounding_box: tuple[float, float, float, float]

Returns bounding box aligned to XY axes in mirror’s base coordinate reference frame.

Returns:: (left, right, bottom, top) bounding box. Mirror’s base coordinate reference frame.
Return type:: Tuple

property children: list[OpticOrientationAbstract]: Returns the children of this instance of OpticOrientationAbstract decendent.

Parametric mirror representing a single reflective surface defined by an algebraic function.

class opencsp.common.lib.csp.MirrorParametric.MirrorParametric(surface_function: Callable[[ndarray, ndarray], ndarray], shape: RegionXY)

Bases: MirrorAbstract

Mirror implementation defined by a parametric function and a 2d region.

__init__(surface_function: Callable[[ndarray, ndarray], ndarray], shape: RegionXY) → MirrorParametric

Instantiates MirrorParametric class

Parameters:

surface_function (Callable[[np.ndarray, np.ndarray], np.ndarray]) – Callable which takes in two ndarrays (the x and y sample coordinates respectively), and outputs the corresponding z height of the mirror from the z=0 plane in ndaray format. surface_function(x, y) = z
shape (RegionXY) – The 2d region of the mirror when looking along the z axis. These 2d points are ‘lifted’ from the z=0 plane to where those points are located as defined by ‘surface_function’.

classmethod generate_flat(shape: RegionXY) → MirrorParametric

Generate a flat, z=0 mirror

Parameters:: shape (RegionXY) – Mirror top-down region.
Return type:: MirrorParametric

classmethod generate_symmetric_paraboloid(focal_length: float, shape: RegionXY) → MirrorParametric

Generate a symmetric parabolic mirror with the given focal length

Parameters:

focal_length (float) – Focal length
shape (RegionXY) – Mirror top-down region.

Return type:

MirrorParametric

surface_displacement_at(p: Pxy) → ndarray[float]

Given an XY sample point in the mirror’s base reference frame, returns the z displacement at the given location in the mirror’s base coordinate reference frame.

Parameters:: p (Pxy) – Sample point in mirror’s base coordinate reference frame.
Returns:: Distance from the z=0 plane in mirror’s base coordinate reference frame.
Return type:: ndarray[float]

surface_norm_at(p: Pxy) → Vxyz

Given an XY sample point in the mirror’s base reference frame, returns the surface normal at the given location in the mirror’s base coordinate reference frame.

Parameters:: p (Pxy) – Sample point in mirror’s base coordinate reference frame.
Returns:: Normal vector of length len(p) in mirror’s base coordinate reference frame.
Return type:: Vxyz

Parametric rectangular mirror wtih origin in center of rectangular region representing a single reflective surface defined by an algebraic function.

class opencsp.common.lib.csp.MirrorParametricRectangular.MirrorParametricRectangular(surface_function: Callable[[float, float], float], size: tuple[float, float] | float)

Bases: MirrorParametric

Mirror implementation defined by a parametric function and rectangular side lengths.

__init__(surface_function: Callable[[float, float], float], size: tuple[float, float] | float) → None

Instantiates a MirrorParametricRectangular object.

Parameters:

surface_function (Callable[[float, float], float]) – See MirrorParametric for details.
size (tuple[float, float] | float) – The size of the mirror. If input type is ‘float,’ outputs square mirror with side lengths equal to size. If input length is 2, size is interpreted as size=(x, y) where x is the x side lengths and y is the y side lengths.

classmethod from_focal_length(focal_length: float, size: tuple[float, float])

class opencsp.common.lib.csp.MirrorPoint.MirrorPoint(surface_points: Pxyz, normal_vectors: Uxyz, shape: RegionXY, interpolation_type: Literal['given', 'bilinear', 'clough_tocher', 'nearest'] = 'nearest')

Bases: MirrorAbstract

A class representing a mirror defined by discrete, scattered surface points and corresponding normal vectors.

This class allows for the representation of a mirror’s surface using a set of points and their associated normal vectors, with options for interpolation methods to define the surface behavior.

__init__(surface_points: Pxyz, normal_vectors: Uxyz, shape: RegionXY, interpolation_type: Literal['given', 'bilinear', 'clough_tocher', 'nearest'] = 'nearest') → None

Initializes a MirrorPoint object with the specified surface points and normal vectors.

Parameters:

surface_points (Pxyz) – The XYZ coordinates of points on the surface of the mirror.
normal_vectors (Uxyz) – The XYZ normal vectors corresponding to the surface points.
shape (RegionXY) – The XY outline of the mirror.
interpolation_type (Literal['given', 'bilinear', 'clough_tocher', 'nearest'], optional) – The type of interpolation to use for the surface and normal vectors (default is ‘nearest’).

Raises:

ValueError – If not all normal vectors have a positive z component.

draw(view: View3d, mirror_style: RenderControlMirror, transform: TransformXYZ | None = None) → None

Draws the mirror in a 3D view.

Parameters:

view (View3d) – The 3D view in which to draw the mirror.
mirror_style (RenderControlMirror) – The style settings for rendering the mirror.
transform (TransformXYZ or None, optional) – A transformation to apply to the mirror when drawing (default is None).

Return type:

None

surface_displacement_at(p: Pxy) → ndarray

Retrieves the surface displacement at a specified point.

Parameters:: p (Pxy) – The point at which to retrieve the surface displacement.
Returns:: The displacement of the surface at the specified point.
Return type:: np.ndarray
Raises:: ValueError – If the point is not within the bounds of the mirror.

surface_norm_at(p: Pxy) → Vxyz

Retrieves the surface normal vector at a specified point.

Parameters:: p (Pxy) – The point at which to retrieve the surface normal.
Returns:: The normalized surface normal vector at the specified point.
Return type:: Vxyz
Raises:: ValueError – If the point is not within the bounds of the mirror.

survey_of_points(resolution: int = 1, resolution_type: str = 'pixelX', random_seed: int | None = None) → tuple[Pxyz, Vxyz]

Surveys points on the mirror surface and retrieves their positions and normals.

Parameters:

resolution (int, optional) – The resolution for sampling points on the mirror surface (default is 1).
resolution_type (str, optional) – The type of resolution to use (default is “pixelX”).
random_seed (int or None, optional) – A seed for random number generation (default is None).

Returns:

A tuple containing the sampled points and their corresponding normal vectors.

Return type:

tuple[Pxyz, Vxyz]

RayTrace and OpticOrientation

class opencsp.common.lib.csp.OpticOrientationAbstract.OpticOrientationAbstract

Bases: ABC

Classes that extend OpticOrientationAbstract are objects that can be in different orientations, and can contain child objects (that also extend OpticOrientationAbstract) that transform with it.

Core Attributes

self._parent: OpticOrientationAbstract: This is the OpticOrientationAbstract object that contains the self. If self is the largest object then this attribute will be None. If an object already has a parent, then it cannot be added to another object as a child. This should be accessed via the @property method self.parent.
self._self_to_parent_transform: TransformXYZ: This is the relatice transformation from the self coordinate frame to the self._parent frame.
(@property) self.children: list[OpticOrientationAbstract]: This property is an abstract method that must be implemented by all deriving classes. There should not be a setter for this attribute. Ideally, there is little information that is stored in two places. However, for both parents and children to find each other, the information about children must be stored in the parent. When implementing self.children, ensure that children hold reference to parents.

Derived Attributes

Other attributes of a OpticOrientationAbstract are calculated based on the other information in the core attributes.

_children_to_self_transform
self_to_global_tranformation
get_transform_relative_to
get_most_basic_optics

This minimized what information must be stored in multiple locations.

__init__() → None

add_child(new_child: ~opencsp.common.lib.csp.OpticOrientationAbstract.OpticOrientationAbstract, new_child_to_self_transform=3D Transform: array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]])): Adds a child to the current optic

get_most_basic_optics() → list[OpticOrientationAbstract]: Return the list of the smallest optic that makes up composite optics.

get_transform_relative_to(target: OpticOrientationAbstract) → TransformXYZ

Gets the transformation from ‘self’ frame to the ‘target’ frame if target is an optic ancestor or decendent of self.

Parameters:

self (OpticOrientationAbstract) – An object that derives OpticOrientationAbstract
target (OpticOrientationAbstract) – An object that derives OpticOrientationAbstract

Returns:

The transformation that takes self to the target frame of reference

Return type:

TransformXYZ

no_parent_copy(): Deep copy of Optic without a parential attachement.

abstract property children: list[OpticOrientationAbstract]: Returns the children of this instance of OpticOrientationAbstract decendent.

property parent: OpticOrientationAbstract: The parent of the current Optic

property self_to_global_tranformation: TransformXYZ

Gets the transformation from ‘self’ frame to the global frame where global is the object in the ancestor tree that does not have a parent.

Parameters:: self (OpticOrientationAbstract) – An object that derives OpticOrientationAbstract
Returns:: The transformation that takes self to the global frame of reference
Return type:: TransformXYZ

class opencsp.common.lib.csp.RayTrace.RayTrace(scene: Scene | None = None)

Bases: object

A class for performing ray tracing in a given scene.

This class manages the ray tracing process, including the collection of light paths and the rendering of the scene based on the light sources and objects present.

__init__(scene: Scene | None = None) → None

Initializes a RayTrace object with the specified scene.

Parameters:: scene (scn.Scene, optional) – The scene in which to perform ray tracing (default is None).

add_many_light_paths(new_paths: list[LightPath])

Adds multiple light paths to the ray trace.

Parameters:: new_paths (list[LightPath]) – A list of LightPath objects to add to the ray trace.
Return type:: None

draw(view: View3d, trace_style: RenderControlRayTrace | None = None) → None

Draws the light paths in a 3D view.

Parameters:

view (View3d) – The 3D view in which to draw the light paths.
trace_style (RenderControlRayTrace, optional) – The style settings for rendering the light paths (default is None).

Return type:

None

draw_subset(view: View3d, count: int, trace_style: RenderControlRayTrace | None = None)

Draws a subset of light paths in a 3D view.

Parameters:

view (View3d) – The 3D view in which to draw the light paths.
count (int) – The number of light paths to draw.
trace_style (RenderControlRayTrace, optional) – The style settings for rendering the light paths (default is None).

Return type:

None

classmethod from_hdf(filename: str, trace_name: str = 'RayTrace') → RayTrace

Creates a RayTrace object from an HDF5 file.

Parameters:

filename (str) – The path to the HDF5 file containing the ray trace data.
trace_name (str, optional) – The name of the trace to load from the file (default is “RayTrace”).

Returns:

A RayTrace object initialized with data from the specified HDF5 file.

Return type:

RayTrace

ray_count() → int

Returns the number of light paths in the ray trace.

Returns:: The number of light paths in the ensemble.
Return type:: int

property light_paths

Retrieves the list of light paths in the ray trace.

Returns:: A list of LightPath objects representing the light paths in the scene.
Return type:: list[LightPath]

opencsp.common.lib.csp.RayTrace.calc_reflected_ray(normal_v: Vxyz, incoming_v: Vxyz) → Vxyz

Calculates the direction of the reflected ray given the incident ray direction and surface normal.

Parameters:

normal_v (Vxyz) – The normal vector at the surface point where the reflection occurs.
incoming_v (Vxyz) – The direction of the incoming ray.

Returns:

The direction of the reflected ray.

Return type:

Vxyz

Notes

The algorithm for reflection is based on the formula:

        ext{reflected_ray} =    ext{incoming_ray} - 2 \cdot (   ext{normal} \cdot       ext{incoming_ray}) \cdot        ext{normal}

norm_v and inc_v must broadcast together.

opencsp.common.lib.csp.RayTrace.ensquared_energy(pts: Vxy, semi_width_max: float, res: int = 50) → tuple[ndarray, ndarray]

Calculate the ensquared energy as a function of square half-width.

This function computes the fraction of ensquared energy within a square defined by the semi-widths, based on the provided points.

Parameters:

pts (Vxy) – A Vxy object containing the points for which to calculate ensquared energy.
semi_width_max (float) – The maximum semi-width of the square in meters.
res (int, optional) – The resolution (number of data points) for the semi-widths (default is 50).

Returns:

np.ndarray – An array containing the fraction of ensquared energy for each semi-width.
np.ndarray – An array of semi-widths in meters.

opencsp.common.lib.csp.RayTrace.histogram_image(bin_res: float, extent: float, pts: Vxy) → tuple[ndarray, ndarray, ndarray]

Creates a 2D histogram from scattered points.

This function generates a histogram image (point spread function) based on the provided points in the XY plane, using specified bin resolution and extent.

Parameters:

bin_res (float) – The resolution of the histogram bins in meters.
extent (float) – The width of the image area in meters.
pts (Vxy) – A Vxy object containing the points to calculate the XY histogram.

Returns:

hist (np.ndarray) – A 2D array representing the histogram image (point spread function).
x (np.ndarray) – A 1D array representing the X axis in meters.
y (np.ndarray) – A 1D array representing the Y axis in meters.

opencsp.common.lib.csp.RayTrace.plane_intersect(ray_trace: RayTrace, v_plane_center: Vxyz, u_plane_norm: Uxyz, epsilon: float = 1e-06, verbose: bool = False, save_in_file: bool = False, save_name: str | None = None, max_ram_in_use_percent: float = 95.0)

Finds all intersections that occur at a specified plane from the light paths in the ray trace.

The output points are transformed from the global reference frame to the local plane reference frame, where the XY plane is perpendicular to the target normal.

Parameters:

ray_trace (RayTrace) – The RayTrace object containing the light paths.
v_plane_center (Vxyz) – The center point of the plane.
u_plane_norm (Uxyz) – The normal vector of the plane.
epsilon (float, optional) – The threshold for determining if a ray is parallel to the plane (default is 1e-6).
verbose (bool, optional) – If True, prints execution status (default is False).
save_in_file (bool, optional) – If True, saves the intersection data to a file (default is False).
save_name (str, optional) – The name of the file to save the intersection data (default is None).
max_ram_in_use_percent (float, optional) – The maximum percentage of RAM to use during processing (default is 95.0).

Returns:

The intersection points in the local plane XY reference frame.

Return type:

Vxy

Raises:

ValueError – If the input parameters are invalid.
MemoryError – If the maximum RAM usage is exceeded during processing.

opencsp.common.lib.csp.RayTrace.process_vector(vec: ndarray, norm: bool = False) → ndarray

Reshapes and converts input vectors to floats.

Parameters:

vec (array-like, shape (3, N) or (3,)) – Input vectors to be processed.
norm (bool, optional) – If True, the vector will be normalized (default is False).

Returns:

A 3xN array of floats, normalized if specified.

Return type:

np.ndarray

opencsp.common.lib.csp.RayTrace.trace_scene(scene: Scene, obj_resolution: Resolution, store_in_ram: bool = True, save_in_file: bool = False, save_name: str | None = None, trace_name: str = 'Default', max_ram_in_use_percent: float = 99, verbose: bool = False) → RayTrace

Traces rays through the scene using a vectorized approach.

Parameters:

scene (scn.Scene) – The scene to trace rays through.
obj_resolution (Resolution) – The resolution for sampling points on objects.
store_in_ram (bool, optional) – If True, the results will be stored in RAM (default is True).
save_in_file (bool, optional) – If True, the results will be saved to a file (default is False).
save_name (str, optional) – The name of the file to save the results (default is None).
trace_name (str, optional) – The name of the trace for saving (default is “Default”).
max_ram_in_use_percent (float, optional) – The maximum percentage of RAM to use during tracing (default is 99).
verbose (bool, optional) – If True, prints updates during processing (default is False).

Returns:

A RayTrace object containing the traced rays.

Return type:

RayTrace

Raises:

UserWarning – If saving is requested but the flag is set to False.
ValueError – If saving is requested but no file name is provided.
MemoryError – If the maximum RAM usage is exceeded before tracing begins.

opencsp.common.lib.csp.RayTrace.trace_scene_parallel(scene: Scene, obj_resolution: Resolution, processor_count: int, resolution_type: str = 'pixelX', store_in_ram=True, max_ram_in_use_percent: float = 99.0, save_in_file=False, save_file_name: str | None = None, trace_name: str = 'RayTrace', verbose: bool = False) → RayTrace

Traces rays through the scene using parallel processing.

This function divides the ray tracing task among multiple processes to improve performance.

Parameters:

scene (scn.Scene) – The scene to trace rays through.
obj_resolution (Resolution) – The resolution for sampling points on objects.
processor_count (int) – The number of processors to use for parallel processing.
resolution_type (str, optional) – The type of resolution to use (default is ‘pixelX’).
store_in_ram (bool, optional) – If True, the results will be stored in RAM (default is True).
max_ram_in_use_percent (float, optional) – The maximum percentage of RAM to use during tracing (default is 99.0).
save_in_file (bool, optional) – If True, the results will be saved to a file (default is False).
save_file_name (str, optional) – The name of the file to save the results (default is None).
trace_name (str, optional) – The name of the trace for saving (default is “RayTrace”).
verbose (bool, optional) – If True, prints updates during processing (default is False).

Returns:

A RayTrace object containing the traced rays.

Return type:

RayTrace

Raises:

UserWarning – If saving is requested but the flag is set to False.
ValueError – If saving is requested but no file name is provided.
MemoryError – If the maximum RAM usage is exceeded before tracing begins.

opencsp.common.lib.csp.RayTrace.trace_scene_unvec(scene: Scene, obj_resolution: int, random_dist: bool = False, store_in_ram: bool = True, save_in_file: bool = False, save_name: str = 'ray_trace_Wed_Mar__5_23_49_21_2025', verbose: bool = False) → RayTrace

DEPRECATED: Traces rays through the scene using an unvectorized approach.

Parameters:

scene (scn.Scene) – The scene to trace rays through.
obj_resolution (int) – The resolution for sampling points on objects.
random_dist (bool, optional) – If True, random distribution of rays will be used (default is False).
store_in_ram (bool, optional) – If True, the results will be stored in RAM (default is True).
save_in_file (bool, optional) – If True, the results will be saved to a file (default is False).
save_name (str, optional) – The name of the file to save the results (default is a timestamped name).
verbose (bool, optional) – If True, prints updates during processing (default is False).

Returns:

A RayTrace object containing the traced rays.

Return type:

RayTrace

Raises:

DeprecationWarning – If this function is called, indicating it is deprecated.

class opencsp.common.lib.csp.RayTraceable.RayTraceable

Bases: object

Abstract class inherited by objects that can be raytraced

abstract most_basic_ray_tracable_objects() → list[RayTraceable]: Return the list of the smallest Ray Traceable that makes up the larger object.

abstract survey_of_points(resolution: Resolution) → tuple[Pxyz, Vxyz]

Returns a set of points sampled from inside the optic region in the optic’s global coordinate reference frame.

Parameters:

resolution (Resolution) – container of the list of points to survey over. If the Resolution is unresolved then it will be resolved in the bounding box of self.

Returns:

A tuple of the points (Pxyz) and normals at the respective points (Vxyz) in
the object’s global coordinate reference frame.

Scene

class opencsp.common.lib.csp.Scene.Scene

Bases: OpticOrientationAbstract

A class representing a scene containing optical elements and light sources.

This class manages a collection of objects that can be ray-traced and light sources that illuminate the scene. It also handles the spatial orientation of these elements.

objects

A list of objects in the scene that can be ray-traced.

Type:: list[RayTraceable]

light_sources

A list of light sources present in the scene.

Type:: list[LightSource]

__init__() → None

Initializes a Scene object with empty lists for objects and light sources.

Parameters:: None

add_light_source(new_light_source: LightSource) → None

Adds a new light source to the scene.

Parameters:: new_light_source (LightSource) – The light source to be added to the scene.
Return type:: None

add_object(new_object: OpticOrientationAbstract) → None

Adds a new object to the scene.

Parameters:: new_object (OpticOrientationAbstract) – The object to be added to the scene.
Return type:: None

draw_objects(view: View3d, render_controls: dict | None = None)

Draws all objects in the scene using the specified rendering controls.

Parameters:

view (View3d) – The view in which to draw the objects.
render_controls (dict[type, RenderControl], optional) – A dictionary mapping object types to their corresponding render control settings (default is None).

Return type:

None

set_position_in_space(child: OpticOrientationAbstract, transform: TransformXYZ) → None

Sets the spatial position of a child object within the scene.

Parameters:

child (OpticOrientationAbstract) – The child object whose position is to be set.
transform (TransformXYZ) – The transformation to apply to the child object.

Raises:

ValueError – If the child is not a member of the scene.

property children: list[OpticOrientationAbstract]

Retrieves the list of child objects in the scene.

Returns:: A list of child objects in the scene.
Return type:: list[OpticOrientationAbstract]

SolarField

class opencsp.common.lib.csp.SolarField.SolarField(heliostats: list[HeliostatAbstract], origin_lon_lat: list[float] | tuple[float, float] | None = None, name: str | None = None, short_name: str | None = None)

Bases: RayTraceable, OpticOrientationAbstract

Representation of a heliostat solar field.

This class manages a collection of heliostats and their configurations, allowing for spatial placement and rendering of the solar field.

__init__(heliostats: list[HeliostatAbstract], origin_lon_lat: list[float] | tuple[float, float] | None = None, name: str | None = None, short_name: str | None = None) → None

Initializes a SolarField object with the specified heliostats and location.

Parameters:

heliostats (list[HeliostatAbstract]) – A list of heliostat objects that make up the solar field.
origin_lon_lat (list[float] | tuple[float, float], optional) – The longitude and latitude of the solar field’s location (default is None).
name (str, optional) – The name of the solar field (default is None).
short_name (str, optional) – A short name for the solar field (default is None).

draw(view: ~opencsp.common.lib.render.View3d.View3d, solar_field_style: ~opencsp.common.lib.render_control.RenderControlSolarField.RenderControlSolarField = <opencsp.common.lib.render_control.RenderControlSolarField.RenderControlSolarField object>, transform: ~opencsp.common.lib.geometry.TransformXYZ.TransformXYZ | None = None) → None

Draws the solar field in a 3D view.

Parameters:

view (View3d) – The 3D view in which to draw the solar field.
solar_field_style (RenderControlSolarField, optional) – The style settings for rendering the solar field (default is a new RenderControlSolarField object).
transform (TransformXYZ, optional) – A transformation to apply to the solar field when drawing (default is None).

Return type:

None

classmethod from_csv_files(long_lat: list[float] | tuple[float, float], heliostat_attributes_csv: str, facet_attributes_csv: str, name=None)

Creates a SolarField object from CSV files containing heliostat and facet attributes.

Parameters:

long_lat (list[float] | tuple[float, float]) – The (longitude, latitude) pair defining the location of the solar field.
heliostat_attributes_csv (str) – The file path to the CSV file containing heliostat attributes.
facet_attributes_csv (str) – The file path to the CSV file describing the facets of the heliostats.
name (str, optional) – An optional name for the solar field (default is None).

Returns:

A SolarField object initialized with the specified attributes.

Return type:

SolarField

heliostat_bounding_box_xy()

Returns an axis-aligned bounding box that only takes into account the heliostat origins.

Returns:: A list containing the minimum and maximum coordinates of the bounding box in the XY plane.
Return type:: list[list[float]]

heliostat_field_regular_grid_xy(n_x: int, n_y: int)

heliostat_name_list() → list[str]

Returns a list of all the names of heliostats in the solar field.

The order is the same as the order the heliostats are stored.

Returns:: A list of heliostat names.
Return type:: list[str]

lookup_heliostat(heliostat_name: str) → HeliostatAbstract

Returns the first HeliostatAbstract in the solar field that matches the given name.

Parameters:: heliostat_name (str) – The name of the heliostat to look up.
Returns:: The matching heliostat object.
Return type:: HeliostatAbstract
Raises:: KeyError – If no heliostat with the specified name exists in the solar field.

set_full_field_face_up()

set_full_field_stow()

set_full_field_tracking(aimpoint_xyz: Pxyz, when_ymdhmsz: tuple)

set_heliostat_positions(positions: list[Pxyz])

Places the heliostats at the specified positions.

Parameters:: positions (list[Pxyz]) – A list of Pxyz objects representing the positions for each heliostat.
Return type:: None
Raises:: ValueError – If the number of positions does not match the number of heliostats.

Notes

The Pxyzs should appear in the same order as the heliostats in self.heliostats.

survey_of_points(resolution: Resolution) → tuple[Pxyz, Vxyz]

Returns a grid of equispaced points and the normal vectors at those points.

Parameters:: resolution (Resolution) – The rectangular resolution of the points gathered.
Returns:: A tuple containing the sampled points and their corresponding normal vectors.
Return type:: tuple[Pxyz, Vxyz]

property children

Retrieves the list of child objects (heliostats) in the solar field.

Returns:: A list of heliostat objects in the solar field.
Return type:: list[RayTraceable]

Tower

Tower Class

class opencsp.common.lib.csp.Tower.Tower(name: str, origin: Pxyz, parts: list[str] = ['whole tower'], height: float = 63.5508, east: float = 5.485, west: float = -5.485, south: float = -9.1186, north: float = 6.25, x_aim: float = 0, y_aim: float = 6.25, z_aim: float = 63.5508, bcs_y_aim: float = 8.8, bcs_z_aim: float = 28.9)

Bases: RayTraceable

Tower representation.

All parameter values are in meters using ENU (East, North, Up) coordinate system. Values are relative to the field coordinates.

Parameters:

namestr: The name of this Tower. Used for special styles given in the draw method.
originPxyz: The center of Tower. All other points in the tower are relative to this value.
partslist[str]: The parts that build the Tower. Includes walls (top, northface, southface, bottom), and optionl target.
heightfloat: The height of Tower. Currently set for NSTTF Tower height of 63.5508 m.
eastfloat: The East wall of the Tower. Currently set for 5.485 m. TODO, MHH find dimensions of tower (in particular width)
westfloat: The West wall of the Tower. Currently set for 5.485 m.
southfloat: The South wall of the Tower. Currently set for 9.1168 m.
northfloat: The North wall of the Tower. Currently set for 6.25 m.
x_aimfloat: The x component of the target in relation to the Tower origin.
y_aimfloat: The y component of the target in relation to the Tower origin.
z_aimfloat: The z component of the target in relation to the Tower origin.

__init__(name: str, origin: Pxyz, parts: list[str] = ['whole tower'], height: float = 63.5508, east: float = 5.485, west: float = -5.485, south: float = -9.1186, north: float = 6.25, x_aim: float = 0, y_aim: float = 6.25, z_aim: float = 63.5508, bcs_y_aim: float = 8.8, bcs_z_aim: float = 28.9): Create a new Tower instance.

Parameters:

name The name of this Tower. Used for special styles given in the draw method.

origin The center of Tower, as a three vector xyz coordinate.

all measurements in meters using ENU coordinate system.

draw(view: View3d, tower_style: RenderControlTower) → None

walls(): Returns the list of walls as top, north, south, and bottom.

northface: The top-left, top-right, bottom-right, bottom-left corners of the Tower, as viewed when standing north of the tower and facing south.

point: The target location given the x, y, and z components.

southface: The top-left, top-right, bottom-right, bottom-left corners of the Tower, as viewed when standing south of the tower and facing north.

Sun

Sun Position Calculation

Adapted from John Clark Craig’s post, “Python Sun Position for Solar Energy and Research.” https://levelup.gitconnected.com/python-sun-position-for-solar-energy-and-research-7a4ead801777

Plotting

Class used to display/save the suite of standard output plots after measuring a CSP Optic object.

class opencsp.common.lib.csp.StandardPlotOutput.StandardPlotOutput

Bases: object

Used to orchestrate the plotting and saving of the standard output plot suite of CSP mirrors

__init__()

plot(): Creates standard output plot suite

optic_measured: MirrorAbstract: Measured optic object

optic_reference: MirrorAbstract: Reference optic object

options_curvature_vis: Curvature visualization options

options_file_output: File output options

options_ray_trace_vis: Ray trace visualization options

options_slope_deviation_vis: Slope deviation visualization options

options_slope_vis: Slope visualization options

params_ray_trace: Parameters to perform ray trace

Abstract class used for visualizing orthorectified slope looking down from +z axis

class opencsp.common.lib.csp.VisualizeOrthorectifiedSlopeAbstract.VisualizeOrthorectifiedSlopeAbstract

Bases: object

Abstract class inherited by all objects which can have orthorectified slope visualization.

get_orthorectified_slope_array(res) → tuple[ndarray, ndarray, ndarray]

Returns slope array given resolution

Parameters:

res (float, optional) – The xy resolution of the plot, meters, by default 0.1

Returns:

slope_array (ndarray) – Shape (2, n, m) array of x/y slopes
x_vec (ndarray) – X interpolation vector
y_vec (ndarray) – Y interpolation vector

abstract orthorectified_slope_array(x_vec: ndarray, y_vec: ndarray) → ndarray

plot_orthorectified_curvature(res: float = 0.1, type_: Literal['x', 'y', 'combined'] = 'combined', clim: float | None = None, axis: Axes | None = None, processing: list[Literal['log', 'smooth']] | None = None, smooth_kernel_width: int = 1)

Plots orthorectified curvature (1st derivative of slope) image on axes.

Parameters:

res (float, optional) – The xy resolution of the plot, meters, by default 0.1
type (str) – Type of slope image to generate - ‘x’, ‘y’, ‘combined’
clim (float | None) – Colorbar limit. Converts to [-clim, clim] for type ‘x’ and ‘y’ and [0, clim] for type ‘combined.’ Units in mrad. None to use default.
axis (plt.Axes | None) – Axes to plot on. Default is None. If None, uses plt.gca().
processing (list[str]) – Apply processing steps to curvature plot. -Log: shows log of absolute value of image -Smooth: Smooths the image with a rectangular kernel of given width.
smooth_kernel_width (int) – Dimension of kernel used to smooth slope image before creating curvature plot. By default, 1.

plot_orthorectified_slope(res: float = 0.1, type_: Literal['x', 'y', 'magnitude'] = 'magnitude', clim: float | None = None, axis: Axes | None = None, quiver_density: float | None = None, quiver_scale: float | None = 50, quiver_color: str = 'white') → None

Plots orthorectified image of mirror slope

Parameters:

res (float, optional) – The xy resolution of the plot, meters, by default 0.1
type (str) – Type of slope image to generate - ‘x’, ‘y’, ‘magnitude’
clim (float | None) – Colorbar limit. Converts to [-clim, clim] for type ‘x’ and ‘y’ and [0, clim] for type ‘magnitude.’ Units in mrad. None to use default.
axis (plt.Axes | None) – Axes to plot on. Default is None. If None, uses plt.gca().
quiver_density (bool | None) – Spacing of quiver arrows in meters, None for no arrows.
quiver_scale (float | None) – Scale of quiver arrows, None for default.
quiver_color (str) – Color of quiver arrows.

plot_orthorectified_slope_error(reference: VisualizeOrthorectifiedSlopeAbstract, res: float = 0.1, type_: Literal['x', 'y', 'magnitude'] = 'magnitude', clim: float | None = None, axis: Axes | None = None, quiver_density: float | None = None, quiver_scale: float | None = 10, quiver_color: str = 'white') → None

Plots slope difference with respect to a reference mirror on axes. Error defined as (self - reference).

Parameters:

reference (VisualizeOrthorectifiedSlopeAbstract) – CSP optic object supporting VisualizeOrthorectifiedSlopeAbstract
res (float, optional) – The xy resolution of the plot, meters, by default 0.1
type (str) – Type of slope image to generate - ‘x’, ‘y’, ‘magnitude’
clim (float | None) – Colorbar limit. Converts to [-clim, clim] for type ‘x’ and ‘y’ and [0, clim] for type ‘magnitude.’ Units in mrad. None to use default.
axis (plt.Axes | None) – Axes to plot on. Default is None. If None, uses plt.gca().
quiver_density (bool | None) – Spacing of quiver arrows in meters, None for no arrows.
quiver_scale (float | None) – Scale of quiver arrows, None for default.
quiver_color (str) – Color of quiver arrows.

abstract property axis_aligned_bounding_box: tuple[float, float, float, float]

Library that handles plotting orthorectified images (slope images, etc.)

opencsp.common.lib.csp.visualize_orthorectified_image.add_quivers(im_x: ndarray, im_y: ndarray, x_vec: ndarray, y_vec: ndarray, quiver_density: float, axis: Axes | None = None, scale: float | None = None, color: str = 'white') → None

Adds quiver arrows to data plot.

Parameters:

im_x/im_y (ndarray) – Images to sample x/y quiver directions from.
x_vec/y_vec (ndarray) – X and Y data grid axes, meters.
quiver_density (float) – Spacing of quiver arrows in meters.
axis ([plt.Axes | None], optional) – Axes to plot on. The default is None. If None, uses plt.gca().
scale ([float | None], optional) – Matplotlib “scale” for adding quiver arrows. The default is None. If None, uses the default scale.
color (str) – Color of the quiver arrows.

opencsp.common.lib.csp.visualize_orthorectified_image.plot_orthorectified_image(image: ndarray, axis: Axes, cmap: str, extent: tuple[float, float, float, float], clims: tuple[float, float], cmap_title: str)

Plots orthorectified image on axes

Parameters:

image (np.ndarray) – 2d image to plot
axis (plt.Axes) – Matplotlib axis to plot on
cmap (str) – Color map
extent (tuple[float, float, float, float]) – Left, right, bottom, top
clims (tuple[float, float]) – Color bar limits [low, high]
cmap_title (str) – Title of colorbar