Python documentationView source ↗
On this page

Scenes, Camera, and Lighting

Scene Contents

Use IDs when a shape must later be replaced or removed:

from cosmol_viewer import Scene, Sphere

scene = Scene()
scene.set("focus", Sphere([0, 0, 0], 1.0).color("#d1495b"))
scene.set("focus", Sphere([1, 0, 0], 1.2).color("#00798c"))
scene.remove_shape("focus")

Replacing or removing named content releases its imported source when no other content in the scene uses it. Selections and other scenes keep their own references. Failed replacements preserve the old content and ownership. recenter_on() stores only the center. Once all owners release an import, passing the CK object again imports its current data.

add() is sufficient for static content that does not need an ID. recenter() changes the scene center and set_scale() applies a global uniform scale.

Reproducible Camera

The orbit camera is represented by azimuth, elevation, roll, distance, target, and vertical field of view:

scene.set_camera_view(
    azimuth=180,
    elevation=0,
    roll=0,
    distance=32,
    target=[0, 0, 0],
    fov=18,
)

Use rotate_camera() for relative changes. set_camera_distance(), set_camera_target(), and set_camera_fov() preserve the other camera components.

For a native interactive viewer, camera parameter logging prints a compact parameter line whenever the camera moves:

from cosmol_viewer import Viewer

viewer = Viewer.show(scene, width=800, height=500)
viewer.camera_parameter_logging(True)

Logging is disabled by default. Native viewers log to the terminal; notebook viewers log to the browser console. To display the parameters in the viewport instead, call viewer.show_camera_parameters(True).

Background and Depth Cueing

scene.set_background_color("#021529")
scene.set_depth_cue(True)
scene.set_depth_cue_range(0.3, 1.0)

Depth cueing fades distant fragments toward the scene background by default. It is disabled initially; its default fractional range is 0.5..1.0. Use set_depth_cue_color() to choose a different cue color. Transparent interactive canvases are enabled with set_transparent_background(True); static exports can independently request a transparent output background.

Lighting

scene.set_lighting(
    ambient=0.55,
    diffuse=0.65,
    specular=1.0,
    intensity=1.0,
    color="#fff7f7",
)

These values approximate the renderer defaults (the default light color is stored as floating-point RGB [1.0, 0.97, 0.97]). set_ambient_light(), set_light_intensity(), and set_light_color() update individual terms.