ChimeraX docs icon

Command: lighting

lightingpreset ]  options

The lighting command controls lighting parameters, through individual options and in convenient preset combinations. Without arguments, lighting reports the current settings in the Log. Colors are reported as red, green, and blue components in the range 0-100 (percentages). See also: material, set, Graphics Toolbar, automatic styling

There are two directional lights, key and fill, plus ambient lighting. The key light is often the dominant source and can cast shadows; the first set of intensity, direction, and color values reported in the Log refer to this light. The fill light serves as a secondary directional source to improve the visibility of regions that would otherwise be dark. The ambient lighting is an approximation to omnidirectional illumination. Shadows cast from multiple uniformly distributed directions can produce ambient shadowing, or “ambient occlusion.”

The preset can be:

The detailed settings within a preset can be listed in the Log by applying the preset and then using the lighting command without arguments. Although there is a preset named default, different settings may be applied by automatic styling based on the size of the first atomic model opened at a time.

The Graphics icon toggles key-light shadows, and if the key light is off, adjusts key-light intensity from 0 to 0.5 to show the shadows.


Parameters that are not specified retain their current values. Below, settings in the simple preset are indicated with bold.

direction  xk,yk,zk
Set key-light direction. Any length vector can be specified; only the direction is used. In simple lighting, the direction is 1,-1,-1. This is from the upper left front to the lower right back in the screen coordinate system (see moveWithCamera),
intensity  Ik
Set key-light intensity (1.0 in simple lighting).
color  color-spec
Set key-light color (white in simple lighting).
fillDirection  xf,yf,zf
Set fill-light direction (approx. -0.2,-0.2,-0.959 in simple lighting).
fillIntensity  If
Set fill-light intensity (0.5 in simple lighting).
fillColor  color-spec
Set fill-light color (white in simple lighting).
ambientIntensity  Ia
Set ambient-light intensity (0.4 in simple lighting).
ambientColor  color-spec
Set ambient-light color (white in simple lighting).
depthCue  true | false
Whether to use depth-cueing, front-to-back shading of the scene (true in simple lighting).
depthCueColor  color-spec
Set depth-cueing color (black in simple lighting). Any transparency in the color will be ignored.
depthCueStart  start
depthCueEnd  end
Set the position of the depth-cueing ramp. Depth-cueing shading increases linearly from start to end, each expressed as a position relative to the front (0.0) and back (1.0) global clipping planes (0.5 to 1.0 in simple lighting). See also: clip
shadows  true | false
Whether the key light should cast shadows (false in simple lighting). This will only have a visible effect when the key light is on (intensity > 0).
qualityOfShadows  coarse | normal | fine | finer | Mk
Set the quality of directional (key-light) shadows. These shadows are rendered with a two-dimensional texture or “depth map.” A small map gives pixelated shadow edges. The integer map size Mk can be specified directly or via one of the quality settings:
depthBias  bk
Set the bias distance for directional shadows, used to avoid a surface shadowing itself due to rounding errors (0.005 of the scene diameter in simple lighting).
multiShadow  N
How many directions should be used to generate ambient shadows (0 in simple lighting, meaning no ambient shadows; maximum 1024).
msMapSize  Ma
Set the size of the depth map for rendering ambient shadows (integer-valued, 1024 in simple lighting).
msDepthBias  ba
Set the bias distance for ambient shadows, used to avoid a surface shadowing itself due to rounding errors (0.01 of the scene diameter in simple lighting). A larger bias is needed for ambient shadows than for directional shadows because a smaller depth map is typically used.
moveWithCamera  true | false
Whether directional lighting should be pinned to the camera viewpoint (screen coordinate system, default) or to the scene coordinate system.

UCSF Resource for Biocomputing, Visualization, and Informatics / March 2017