Command Line Usage

<< Previous: Loading Catalog Files

Next: Movie Recording >>


Cosmographia may be launched from the command line with the following arguments:
      % Cosmographia -u “url” -p script catalog catalog …
      url is the URL string defining a Cosmographia state, described in detail below.
      script is the name of a Python script to be executed by the program.
      catalog are the names of additional catalog files to be loaded at start up.
Command line arguments can be provided in any order. When processing the command line Cosmographia first loads all catalog files in the order in which they are given, then uses information from the state URL to initialize camera position/orientation and time, and finally executes the Python script.
Catalog and script file names can be specified with absolute paths [in all program versions] or relative paths [in Cosmographia 4.1 or later].

State URL

State URL is a string formatted as a URL query string, containing information about Cosmographia center object, time and time step, rendering frame, and camera position and orientation. Cosmographia state URLs have the following form:
      center is the Cosmographia name of of the central object, e.g. Titan.
      parameter is the parameter name.
      value is the parameter value.
The following parameters can be present in a valid state URL:
      select=objectname is the name of the selected object. e.g. Titan.
      frame=frame is the selected rendering frame; can be icrf or bfix or track.
      ftarget=objectname is the name of the tracked body for track frame. e.g. Sun.
      jd=number is the time given as Julian Date Ephemeris Time, e.g. 2453305.138169.
      x=number is the camera position X coordinate, in km, e.g . 7556.223087.
      y=number is the camera position Y coordinate, in km, e.g. -8251.195605.
      z=number is the camera position Z coordinate, in km, e.g. 8710.933466.
      qw=number is the camera orientation quaternion scalar element, e.g. 0.854340.
      qx=number is the camera orientation quaternion X vector element, e.g. 0.399719.
      qy=number is the camera orientation quaternion Y vector element, e.g 0.181822.
      qz=number is the camera orientation quaternion Z vector element, e.g. 0.277973.
      ts=number is time step, in seconds, e.g -10, -1, 0 (for pause), 1, 100, etc.
      fov=number is the camera FOV size (vertical extent) in degrees, e.g. 50.
The camera position (x,y,z) and quaternion (qw,qx,qy,qz, SPICE-style) parameters define position and  orientation of the camera relative to the selected central object (center) and rendering frame (frame). The frame values icrfbfix, or track stand for inertial, body-fixed, and locked rendering frames correspondingly. A synodic frame currently cannot be specified in a state URL but a locked frame with the tracked body set to the center of motion can be used instead.
For Cosmographia to correctly visualize the desired camera and time state all of the parameters above should be present in a state URL. The exceptions are select, which is optional, and ftarget, which must be present only if frame=track.
This is an example of a valid state URL:

Capturing State URLs

State URLs can be captured from within the program by pressing COMMAND-U. This places the complete URL corresponding to the current program state into the clipboard from which the URL can be pasted into other applications.
Because synodic and vector-based frames are not supported by the current state URL parameters, the URLs captured when the rendering frame is set to synodic or vector-based incorrectly label the frame as icrf.

Invoking Cosmographia from a Script

The ability to capture a state URL using COMMAND-U and provide it along with the names of all needed catalog files on the program’s command line allows users to create simple shell scripts that launch Cosmographia with the view containing  desired additional objects seen at the desired time from the desired point of view.
This is an example of such a C-shell script launching the program to get a good view of a CASSINI RADAR observation of Titan:
      Cosmographia \
        ~/cosmographia/CASSINI/load_CASSINI-RADAR_3-TITAN.json \
        -u “cosmo:Titan?select=Titan&frame=bfix&jd=2453305.138169&
A Windows batch file for the same view would look like this:
      Cosmographia ^
      %HOMEPATH%\cosmographia\CASSINI\load_CASSINI-RADAR_3-TITAN.json ^
      -u “cosmo:Titan?select=Titan&frame=bfix&jd=2453305.138169&