Command: lighting

Usage:
lighting [ preset ]  options

Usage:
lighting model  spec   model-options

The lighting command controls global lighting parameters, through individual options and in convenient preset combinations. Related per-model settings can be adjusted with the lighting model command. The material command sets material properties for light reflection and whether mesh surfaces and transparent objects cast shadows. See also: preset, graphics, Graphics icons, automatic styling

Given 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). 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. Regardless of whether shadows are on, the directional lights cause “shading,” where the brightness of an object varies based on the angle between the light direction and the surface normal. The key light also produces directionally dependent specular highlights. 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:

• default or simple – all three kinds of light, but no shadows (details...)
• full – all three kinds of light, key light with shadows, ambient lighting with shadowing from 64 directions (details...)
• soft – ambient lighting only, ambient shadowing from 64 directions (details...)
  • to decrease a sooty/smudgy appearance, try gentle instead and/or increase the multishadow directions, e.g. with lighting multiShadow 512
  • in general, however, ambient shadowing works better with space-filling representations such as surfaces than with more sparse representations such as cartoons and sticks
• gentle – same as soft, except tuned to emphasize larger indentations (details...)
• flat – ambient lighting only, no shadows (details...)
  • this preset also turns silhouettes on; for silhouettes off, use or graphics silhouettes false

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.

[back to top: lighting]

Options

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

direction  x_k,y_k,z_k
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  I_k
Set key-light intensity (1.0 in simple lighting).

color  color-spec
Set key-light color (white in simple lighting).

fillDirection  x_f,y_f,z_f
Set fill-light direction (approx. -0.2,-0.2,-0.959 in simple lighting).

fillIntensity  I_f
Set fill-light intensity (0.5 in simple lighting).

fillColor  color-spec
Set fill-light color (white in simple lighting).

ambientIntensity  I_a
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). See also per-model settings.

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). See also per-model settings.

qualityOfShadows  coarse | normal | fine | finer | M_k
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 M_k can be specified directly or via one of the quality settings:

• coarse – map size 1024
• normal (as in simple lighting) – map size 2048
• fine – map size 4096
• finer – map size 8192

depthBias  b_k
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). See also per-model settings.

msMapSize  M_a
Set the size of the depth map for rendering ambient shadows (integer-valued, 1024 in simple lighting).

msDepthBias  b_a
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.

[back to top: lighting]

Per-Model Lighting Options

Usage: lighting model  spec  [ depthCue  true | false ] [ directional  true | false ] [ shadows  true | false ] [ multiShadow  true | false ]

The lighting model command allows turning off a setting for an individual model or models when that setting is globally enabled. If the setting is globally disabled, the per-model settings will not be evident.

depthCue  true | false
Whether depth-cueing should apply to the specified model(s) when depth-cueing is enabled globally.

directional  true | false
Model(s) for which this setting is false will appear as flat, without any directional shading, highlights, or shadows. They will also be unaffected by changes in ambient lighting, but depth-cueing may still apply.

shadows  true | false
Whether the key light should cast shadows on the specified model(s). This will only have a visible effect when the key light is on (intensity > 0) and shadows are enabled globally.

multiShadow  true | false
Whether ambient shadowing should be shown on the specified model(s) when ambient shadowing is enabled globally (number of directions N > 0).

[back to top: lighting]

Lighting Preset Details

Intensity: 1
Direction: 0.577,-0.577,-0.577
Color: 100,100,100
Fill intensity: 0.5
Fill direction: -0.2,-0.2,-0.959
Fill color: 100,100,100
Ambient intensity: 0.4
Ambient color: 100,100,100
Depth cue: 1, start 0.5, end 1, color 0,0,0
Shadow: False (depth map size 2048, depth bias 0.005)
Multishadows: 0 (max 1024, depth map size 1024, depth bias 0.01)

Intensity: 0.7
Direction: 0.577,-0.577,-0.577
Color: 100,100,100
Fill intensity: 0.3
Fill direction: -0.2,-0.2,-0.959
Fill color: 100,100,100
Ambient intensity: 0.8
Ambient color: 100,100,100
Depth cue: 1, start 0.5, end 1, color 0,0,0
Shadow: True (depth map size 2048, depth bias 0.005)
Multishadows: 64 (max 1024, depth map size 1024, depth bias 0.01)
  VR Multishadows: 8 

Intensity: 0
Direction: 0.577,-0.577,-0.577
Color: 100,100,100
Fill intensity: 0
Fill direction: -0.2,-0.2,-0.959
Fill color: 100,100,100
Ambient intensity: 1.5
Ambient color: 100,100,100
Depth cue: 1, start 0.5, end 1, color 0,0,0
Shadow: False (depth map size 2048, depth bias 0.005)
Multishadows: 64 (max 1024, depth map size 1024, depth bias 0.01)
  VR Multishadows: 8 

Intensity: 0
Direction: 0.577,-0.577,-0.577
Color: 100,100,100
Fill intensity: 0
Fill direction: -0.2,-0.2,-0.959
Fill color: 100,100,100
Ambient intensity: 1.5
Ambient color: 100,100,100
Depth cue: 1, start 0.5, end 1, color 0,0,0
Shadow: False (depth map size 2048, depth bias 0.005)
Multishadows: 64 (max 1024, depth map size 128, depth bias 0.05)

Intensity: 0
Direction: 0.577,-0.577,-0.577
Color: 100,100,100
Fill intensity: 0
Fill direction: -0.2,-0.2,-0.959
Fill color: 100,100,100
Ambient intensity: 1.45
Ambient color: 100,100,100
Depth cue: 1, start 0.5, end 1, color 0,0,0
Shadow: False (depth map size 2048, depth bias 0.005)
Multishadows: 0 (max 1024, depth map size 1024, depth bias 0.01)