pyblenderSDIC.SpotLight#

class SpotLight(frame: ~py3dframe.frame.Frame = Frame(origin=[[0.] [0.] [0.]], x_axis=[[1.] [0.] [0.]], y_axis=[[0.] [1.] [0.]], z_axis=[[0.] [0.] [1.]], energy: float = 1.0, spot_size: float = 3.141592653589793, spot_blend: float = 0.0)[source]#

Bases: object

Represents a spot light in 3D space with a defined position and orientation.

The spot light orientation is defined by the frame. The spot light emits along the z-axis of the frame.

The frame of the light defines the orientation of the camera in 3D space with (convention OPENCV):

origin: The position of the light in 3D space.
x-axis: any direction perpendicular to the optical axis of the light.
y-axis: any direction perpendicular to the optical axis of the light.
z-axis: The optical axis of the light (from the light to the scene).

The attribute spot_size is the apperture angle of the spot light. It is defined as the angle between the two edges of the cone of light emitted by the spot light. The figure below shows the definition of the spot light size in Blender (Image source: Blender Manual)

../_images/blender_spot_light_size.png — Blender spot light size definition.#

The attribute spot_blend is the proportion of the spot light this a smooth transition between the spot light and the background light. Setting the spot_blend to 0.0 will create a sharp transition between the spot light and the background light.

Parameters:

frame (Frame, optional) – The frame of the camera. (see py3dframe : https://https://artezaru.github.io/py3dframe/), default Frame().
energy (float, optional) – The energy of the spot light. The energy this light would emit over its entire area if it wasn’t limited by the spot angle, default 1.0.
spot_size (float, optional) – The size of the spot light in radians, default is numpy.pi.
spot_blend (float, optional) – The blend value of the spot light between 0 and 1, default 0.0.

property energy: float#

Get or set the energy of the spot light.

The energy of the spot light. The energy this light would emit over its entire area if it wasn’t limited by the spot angle. The energy is used to calculate the intensity of the light in the scene.

Returns:: The energy of the light.
Return type:: float

property frame: Frame#

Get or set the frame of the spot light.

The spot light emits along the z-axis of the frame.

The frame of the light defines the orientation of the camera in 3D space with (convention OPENCV):

origin: The position of the light in 3D space.

x-axis: any direction perpendicular to the optical axis of the light.

y-axis: any direction perpendicular to the optical axis of the light.

z-axis: The optical axis of the light (from the light to the scene).

See also

https://artezaru.github.io/py3dframe/ for more information about the frame.

Returns:: The frame of the light.
Return type:: Frame

classmethod from_dict(data: Dict) → SpotLight[source]#

Create a SpotLight instance from a dictionary.

The structure of the dictionary should be as provided by the pyblenderSDIC.SpotLight.to_dict() method.

Parameters:: data (dict) – A dictionary containing the spot light’s data.
Returns:: The SpotLight instance.
Return type:: SpotLight
Raises:: ValueError – If the data is not a dictionary.

classmethod from_json(filepath: str) → SpotLight[source]#

Create a SpotLight instance from a JSON file.

The structure of the JSON file follows the pyblenderSDIC.SpotLight.to_dict() method.

Parameters:: filepath (str) – The path to the JSON file.
Returns:: A SpotLight instance.
Return type:: SpotLight
Raises:: FileNotFoundError – If the filepath is not a valid path.

get_OpenCV_RT() → Tuple[Rotation, ndarray][source]#

Get the rotation and translation of the spotlight in the OpenCV format.

The axis of the spotlight frame for OpenCV are the same as the spotlight frame. Furthermore, the convention for OpenCV is \(X_{light} = R X_{world} + T\), convention=4 for py3dframe.

Returns:

Rotation – The rotation of the light.
numpy.ndarray – The translation of the light with shape (3, 1).

get_OpenGL_RT() → Tuple[Rotation, ndarray][source]#

Get the rotation and translation of the light in the OpenGL format.

The axis of the light frame for OpenGL are different from the SpotLight frame: - x-axis: The same as the SpotLight frame : right direction of the light (left to right). - y-axis: The opposite of the SpotLight frame : up direction of the light (down to up). - z-axis: The opposite of the SpotLight frame : (from the scene to the light).

Furthermore, the convention for OpenGL is \(X_{world} = R X_{cam} + T\), convention=0 for py3dframe.

Note

The OpenGL format is used in Blender.

Returns:

Rotation – The rotation of the light.
numpy.ndarray – The translation of the light with shape (3, 1).

set_OpenCV_RT(rotation: Rotation, translation: ndarray) → None[source]#

Get the rotation and translation of the spotlight in the OpenCV format.

The axis of the spotlight frame for OpenCV are the same as the spotlight frame. Furthermore, the convention for OpenCV is \(X_{light} = R X_{world} + T\), convention=4 for py3dframe.

Parameters:

rotation (Rotation) – The rotation of the light.
translation (numpy.ndarray) – The translation of the light with shape (3, 1).

set_OpenGL_RT(rotation: Rotation, translation: ndarray) → None[source]#

Set the rotation and translation of the light in the OpenGL format.

Furthermore, the convention for OpenGL is \(X_{world} = R X_{cam} + T\), convention=0 for py3dframe.

Note

The OpenGL format is used in Blender.

Parameters:

rotation (Rotation) – The rotation of the light.
translation (numpy.ndarray) – The translation of the light with shape (3, 1).

property spot_blend: float#

Get or set the spot_blend value of the spot light.

Returns:: The spot blend value of the light between 0 and 1.
Return type:: float

property spot_size: float | None#

Get or set the spot_size of the spot light.

Returns:: The spot size of the light in radians.
Return type:: float

to_dict(description: str | None = None) → Dict[source]#

Export the SpotLight’s data to a dictionary.

The structure of the dictionary is as follows:

{
    "type": "SpotLight [pyblenderSDIC]",
    "description": "Description of the spot light",
    "frame": {
        "translation": [0.0, 0.0, 0.0],
        "quaternion": [1.0, 0.0, 0.0, 0.0],
        "convention": 0,
        "parent": None
    },
    "energy": 10.0,
    "spot_size": 0.985,
    "spot_blend": 0.5
    }
}

Parameters:: description (Optional[str], optional) – A description of the spot light, by default None. If provided, it will be included in the dictionary under the key “description”.
Returns:: A dictionary containing the spot light’s data.
Return type:: dict
Raises:: ValueError – If the description is not a string.

to_json(filepath: str, description: str | None = None) → None[source]#

Export the SpotLight’s data to a JSON file.

The structure of the JSON file follows the pyblenderSDIC.SpotLight.to_dict() method.

Parameters:

filepath (str) – The path to the JSON file.
description (Optional[str], optional) – A description of the spot light, by default None. If provided, it will be included in the JSON file under the key “description”.

Raises:

FileNotFoundError – If the filepath is not a valid path.

pyblenderSDIC.SpotLight#

This Page