Cell:// URL questions

[don]

Howdy Everyone,

I am hoping one of the Celestia developers (or someone else "in the know") could fill in the blanks below, as to what each of the possible variables stored in a Cel// URL are? This would help me to determine values to enter into a script. The "blanks" (no description) are denoted by the text "(???)".

For the seemingly encrypted data strings (?x, &y, &z), is it possible to provide a list of what values are possible in each of the string's positions, and a definition of what each one is?

Thank you for sharing your knowledge to help me write a .CEL scripting guide!

-Don

Code: Select all

---------------------------------------

List of Cel:// URL Variables
----------------------------
Header (cel:)

String -- to be parsed.  Consists of ...
  * //<text> (???) What are all of the possible entries here?
      (some possible entries from Selden's doc...)
    - Freeflight
    - Follow
    - SyncOrbit
    - Chase
    - PhaseLock
    - Equatorial & ObserverLocal = "Unknown"
    - (???) others

  * /<text> (zero or more objects/object paths depending on previous variable)
  * /Date   (Date)
  * Ttime   (Time)

?x: <?encrypted data> (???) ... Example: ?x=HBq/urajN5/EDA

Note: All variables below are actually prefixed with an ampersand (&), which had to be removed in order for the text to display properly here in the forum.

y: <?encrypted data> (???) ... Example: &y=9pEV0xeFCQ

z: <?encrypted data> (???) ... Example: &z=baLmLZOzTXkO

ow: <number> (???)

ox: <number> (???)

oy: <number> (???)

oz: <number> (???)

track: <object/object path> (Currently Tracked object)

select: <object/object path> (Currently selected object)

fov: <number> (Field Of View)

ts: <number> (Time Rate / X-factor)

rf: <number> (rf1 ???)

lm: <number> (lm1 ???)

ltd <number> (???)

rf: <number> (rf2 ???)

lm: <number> (lm2 ???)
 
 
??? Are there any other variables I missed?

NOTE: The duplicate entries of "rf" and "lm" are not typos.  This list was generated by Celestia 1.3.1 pre6 when all Rendering options were turned ON, except Comet Labels (the checkbox does not stay checked).  I reported this as a possible bug in the Bug forum.



[selden]

Don,

I'm having a little trouble understanding your question. Are you trying to document the URLs so someone could create one?

I'm not a developer, but from what I was told by someone who is...

People should not be trying to create Cel://URLs by hand.
They're primarily hexadecimal dumps of Celestia's internal state, and as a result the format is subject to change without notice (although they try to keep them upward-compatible).

Cel:// URLs should only be created by Celestia's "Control-Insert" keyboard command (under Windows XP, at least, I'm not sure if that's necessarily the command used under Linux or MacOS X).

Is this a relevant answer?

[don]

Hi Selden,

No, I'm not trying to create / re-create a Cel:// URL.

I would like to know what each of the variables is because the data they contain can be placed into corresponding variables in scripts (vectors, axis, and that kind of stuff). It can provide folks who are writing a script with information that is not available in any other way.

It would be great to be able to press a key in Celestia and have it run a function that places all of the existing variabes that could possibly be used in a script, onto the Windows clipboard. But, that's a new feature request (smile).

As an example for my question ... you've positioned yourself to "just the right spot" somewhere in space and time. Now, in the script you are writing, you want to duplicate that exact position (the script has many other positions as well). So, you save your position to the favorites.cel file (using the Bookmark, Locations, or whatever the menu option ends up being) and, if it's simply not duplicate information (which is what I'm trying to find out), press Ctrl+Ins to get the Cell:// URL information in the clipboard.

Now, between these two sources of information, you *should* have enough information (if you know what the variables are and where to place them in the script) that you should be able to duplicate your "just the right spot" in space and time position.

Does this help?

-Don

[don]

PS. If the seemingly encrypted strings are actually encrypted, then it would be of no use to me/other scripters.

Well, actually it WOULD, but it would be better provided as UN-encrypted. I am assuming it contains render flags, etc. kind of info.

[selden]

OK, I understand now, I think.

Unfortunately, my advice would have to be "look at the code".
(That's what I'd have to do to try to answer.)

[selden]

My understanding is that they're not encrypted, except insofar as they really do include memory dumps of the various flags. As a result, they're likely to change from one release to another as flags are reorganized, deleted, added, etc.

[don]

On the "new feature" train of thought...

If the Cel:// URL contains EVERY piece of information necessary to exactly duplicate the current condition, settings and position in Celestia, how about adding another keystroke to provide this information in a human-readable fashion (on the clipboard is fine) so that a scripter could also use it to exactly duplicate everything?

This could use existing routines, except for the encryption of the first 3 strings, and would hopefully give real variable names that are used in the .CEL scripting language. Such as CoordinateSystem (not 'upframe'), Date, TimeRate, Speed, (axis, xrot, yrot, zrot, base, and offset -- hopefully using descriptive names), VisibilityMagnitude, AmbientLight, etc.

-Don

[don]

OK, I understand now, I think.

Unfortunately, my advice would have to be "look at the code".
(That's what I'd have to do to try to answer.)

I've tried ... and failed (sigh).

That's why I'm asking for developer assistance on this one.

[chris]

The x, y, and z fields of a cel:// URL give the position. They're not encrypted; rather, they are base-64 encodings of the 128-bit fixed point numbers used by Celestia for high-precision coordinates. Representing them using decimal digits would be more work and make them less compact.

How about a script function that accepts a cel:// URL as an argument and then sets the position, orientation, and other state? Would that suffice?

--Chris

[don]

How about a script function that accepts a cel:// URL as an argument and then sets the position, orientation, and other state? Would that suffice?

--Chris

Thank you for your reply Chris.

Suffice? That would be icing on a very delicious cake!

And would save scripters a lot of "legwork" deciphering data and coding it into their scripts.

Thank you!

-Don

[don]

Hi Chris,

When this one gets around to being implemented, please let me know *how* it's implemented (command name, parameters, etc.) along with an example of how to use it -- so I can put it in the Guide.

Thanks again!

-Don

[Christophe]

I've corrected the duplicate rf and lf entries, that was a bug.

For reference, there are three types of cel:// URLs:

1- Standard (Absolute) URLs generated with CTRL-C of CTRL-Ins.
2- Relative (KDE: ALT-R) - relative position to the body, no time setting.
3- Setting (KDE: CTRL-ALT-S) - no position nor time only settings.

The current 'grammar' is:

1- For Absolute URLs:
cel://Mode/[body1[/body2]]/TimeStamp?vars
With:
Mode: value (number of bodies)
- Freeflight (0)
- Follow (1)
- SyncOrbit (1)
- Chase (1)
- Phaselock (2)
body1 and body2 are the body names (complete pathname with ':' instead of '/').
TimeStamp: is an ISO-8601 UTC date and time YYYY-MM-DDThh:mm:ss.sssss
vars: URL-encoded variables
- x, y, and z: 64 bits coordinates encoded in Base64.
- ow, ox, oy, oz: orientation vector coordinates
- track: tracked object's pathname
- select: selected object's pathname
- fov: field of view
- ts: time scale
- ltd: light time delay |0|1]
- rf: render flag
- lm: label mode.

2- For Relative URLs:
cel://Mode/[body1[/body2]]/?vars
Mode: same as for Absolute URLs
vars:
- dist: distance to body center
- long: longitude
- lat: latitude
- track: tracked object's pathname
- select: selected object's pathname
- fov: field of view
- ts: time scale
- ltd: light time delay |0|1]
- rf: render flag
- lm: label mode.

3- For Setting URLs:
cel://Settings/?vars
vars:
- rf: render flag
- lm: label mode.

[don]

Thank you Christophe. The duplicate vars was reported in another topic (1.3.1 p6 - Cell:// URLs) and I see you've read it.

Thank you very much for the reference information. Folks writing a script can use pieces of it, such as orientation, and I understand that it may change from time to time, so I will note this fact/warning in the Scrupting Guide as well.

As an aside to Chris' message regarding my asking about a keystroke (or script function) to provide the data in human-readable form to a scripter ... to me, a Cell://URL is a goto command along with all the data necessary to duplicate the saved view, position, etc. and a goto is executed in a matter of a couple of seconds and is a direct route, where the scripter has no control over any velocity (accel, cruise, decel, etc.), flight path, view, etc. *during* the trip.

That's why I say this data could be *very useful* to a scripter, if it could be provided much like the data in the favorites.cel file, so the scripter could create their own flight path, using move instead of goto, (doing some sight seeing on the way if necessary) and then end-up at the target coordinates in the correct position, orientation, etc. with all the appropriate flags and display options set the way the view was originally saved.

Chris, is this what you envisioned when you wrote "... a script function that accepts a cel:// URL as an argument and then sets the position, orientation, and other state?"? It doesn't sound quite the same. It would be better to have a script function that contains all of the variables in a format that can be used within the script itself, using existing commands (setposition, setorientation, etc.), and then let the scripter control *how* the view changes (speed, path, etc.) to get to the target "place".

Do you understand what I'm trying to say? I'd rather have the data so I can control the flight, instead of "zipping" (goto) across the universe or through an entire galaxy in one second flat -- and maybe *not* take the most direct route either.

Thanks again!

-Don