Blender SpotLight Class#

class BlenderSpotLight(frame=None, energy=1.0, spot_size=3.141592653589793, spot_blend=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)[source]#

Create a BlenderSpotLight instance from a dictionary.

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

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

classmethod from_json(filepath)[source]#

Create a BlenderSpotLight instance from a JSON file.

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

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

get_OpenCV_RT()[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).

Return type:

Tuple[Rotation, ndarray]

get_OpenGL_RT()[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 BlenderSpotLight frame: - x-axis: The same as the BlenderSpotLight frame : right direction of the light (left to right). - y-axis: The opposite of the BlenderSpotLight frame : up direction of the light (down to up). - z-axis: The opposite of the BlenderSpotLight 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).

Return type:

Tuple[Rotation, ndarray]

set_OpenCV_RT(rotation, translation)[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).

Return type:

None

set_OpenGL_RT(rotation, translation)[source]#

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

The axis of the light frame for OpenGL are different from the BlenderSpotLight frame: - x-axis: The same as the BlenderSpotLight frame : right direction of the light (left to right). - y-axis: The opposite of the BlenderSpotLight frame : up direction of the light (down to up). - z-axis: The opposite of the BlenderSpotLight 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.

Parameters:

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

Return type:

None

property spot_blend: float#

Get or set the spot_blend value of the spot light.

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.

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.

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)

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

to_dict(description=None)[source]#

Export the BlenderSpotLight’s data to a dictionary.

The structure of the dictionary is as follows:

{
    "type": "BlenderSpotLight",
    "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, description=None)[source]#

Export the BlenderSpotLight’s data to a JSON file.

The structure of the JSON file follows the 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.

Return type:

None

Blender SpotLight Class#

This Page