Celestia/Celx Scripting/CELX Lua Methods/CEL command lock

lock

lock { }

This command locks two objects together. The first object selected is called the reference object, and the second object selected is called the target object. When they are locked together as a pair, as you rotate the scene, the target object stays locked to the reference object, and the distance displayed is the distance between the two objects.

In Lock mode, your position remains fixed relative to a line between the reference object and the target object. As the target object moves around the reference object (relatively speaking) so do you. Thus if the target object is Sol, the illuminated fraction of the reference object (its "phase") remains the same because you're moving around the object in sync with Sol.

The command has no arguments.

CELX equivalent-1:

Based on the observer:setframe() method.

• Find and select the reference object with name <refstring> and store in "objectname_ref".

objectname_ref = celestia:find( <refstring> )
celestia:select(objectname_ref)

• Find the target object with name <tarstring> which must be locked with "objectname_ref" and store in "objectname_tar".

objectname_tar = celestia:find( <tarstring> )

• Set the coordinate system of the frame of reference to lock with "objectname_tar" as target-object and "objectname_ref" as reference and store in "frame".

frame = celestia:newframe("lock", objectname_ref, objectname_tar)

• Get observer instance of the active view instance and set the coordinate system of the frame of reference to "frame".

obs = celestia:getobserver()
obs:setframe(frame)

Summarized:

objectname_ref = celestia:find( <refstring> )
celestia:select(objectname_ref)
objectname_tar = celestia:find( <tarstring> )
frame = celestia:newframe("lock", objectname_ref, objectname_tar)
obs = celestia:getobserver()
obs:setframe(frame)

CELX equivalent-2:

Based on the observer:lock() method.

• Find and select the reference object with name <refstring> and store in "objectname_ref".

objectname_ref = celestia:find( <refstring> )
celestia:select(objectname_ref)

• Find the target object with name <tarstring> which must be locked with "objectname_ref" and store in "objectname_tar".

objectname_tar = celestia:find( <tarstring> )

• Get observer instance of the active view and activate lock-mode on the axis from "objectname_tar" to "objectname_ref" selected object.
  Lock-mode is the same as setting the frame of reference to lock with "objectname_tar"” as target-object and "objectname_ref" as reference.

obs = celestia:getobserver()
obs:lock(objectname_tar)

Summarized:

objectname_ref = celestia:find( <refstring> )
celestia:select(objectname_ref)
objectname_tar = celestia:find( <tarstring> )
obs = celestia:getobserver()
obs:lock(objectname_tar)

Example:
The example below will maintain your position with respect to the center of the Earth, and keep both the Sun (Sol) and the Earth at a fixed location in the camera view. It's the same as if you typed the following key sequence on your keyboard: [3] key → [F] key → [0] key (zero) → [shift + :] keys.

CEL:

select { object "Sol/Earth" }
follow { }
select { object "Sol" }
lock   { }

CELX with the observer:lock() method:

-- Activate Lock-mode on target object.
objectname_ref = celestia:find("Sol/Earth")
celestia:select(objectname_ref)
objectname_tar = celestia:find("Sol")
obs = celestia:getobserver()
obs:lock(objectname_tar)

CELX with the observer:setframe() method:

-- Set the coordinate system of the frame of reference to lock.
objectname_ref = celestia:find("Sol/Earth")
celestia:select(objectname_ref)
objectname_tar = celestia:find("Sol")
frame = celestia:newframe("lock", objectname_ref, objectname_tar)
obs = celestia:getobserver()
obs:setframe(frame)

Back to CEL command index