Main Content

Light

Light source

Since R2023b

expand all in page

    Description

    A Light object represents a light source within a scene. The properties of the object control the appearance and behavior of the light source.

    Creation

    Syntax

    l = images.ui.graphics3d.Light
    l = images.ui.graphics3d.Light(Name=Value)

    Description

    example

    l = images.ui.graphics3d.Light creates a Light object with default property values. Use l to query and modify properties of the Light object after you create the object.

    l = images.ui.graphics3d.Light(Name=Value) sets properties of the object using one or more name-value arguments. For example, images.ui.graphics3d.Light(Intensity=0.8) creates a Light object with an intensity of 0.8.

    Properties

    expand all

    Light source is enabled, specified as "on" or "off", or as a numeric or logical 1 (true) or 0 (false). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

    When this value is "on" (the default value), the light source is enabled. You can specify the Enabled property for individual Light objects, or update all light objects in a Viewer3D object by setting the Lighting property of the viewer. For example, specifying the Lighting value as "off" automatically updates the Enabled property value for all Light objects associated with the Viewer3D object to "off".

    Location of the light source, specified as a 3-element vector of the form [x y z]. This value specifies the point from which the light illuminates the viewer scene, in world coordinates.

    Intensity of the light source, specified as a numeric scalar in the range [0, 1]. A greater value corresponds to a brighter light source.

    Size of the light source, specified as a numeric scalar in the range [0, 1]. This property affects the visualization of only those Volume objects displayed using cinematic rendering, meaning the value of the RenderingStyle property of the Volume object is "CinematicRendering". A value of 0 specifies a point light source. A value of 1 specifies a light the same size as the bounding sphere that contains all objects in the viewer.

    Mode for the light position, specified as one of these values.

    • "headlight" — Light is at the camera location and moves with the camera.

    • "right" — Light is above and to the right of the camera and moves with the camera.

    • "left" — Light is above and to the left of the camera and moves with the camera.

    • "camera-above" — Light is above the camera and moves with the camera.

    • "target-right" — Light is to the right of the camera target and moves with the camera.

    • "target-left" — Light is to the left of the camera target and moves with the camera.

    • "target-above" — Light is above the camera target and moves with the camera.

    • "target-below" — Light is below the camera target and moves with the camera.

    • "target-behind" — Light is behind the camera target and moves with the camera.

    • "manual" — The light is at the position specified by the Position property. The light does not move with the camera.

    • "auto" — The light moves with the camera.

    Examples

    collapse all

    Open Live Script

    Create a light source object with default property values.

    light1 = images.ui.graphics3d.Light
    light1 = 
  Light with properties:

         Enabled: on
        Position: [0 0 0]
    PositionMode: "right"
       Intensity: 0.6000
            Size: 0.1500

    Create a light source object located up and to the left of the camera.

    light2 = images.ui.graphics3d.Light(PositionMode="left")
    light2 = 
  Light with properties:

         Enabled: on
        Position: [0 0 0]
    PositionMode: "left"
       Intensity: 0.6000
            Size: 0.1500

    Version History

    Introduced in R2023b

    See Also

    | | |