View source for Coordinate Systems

== Coordinate systems in Jmol ==

When a file is loaded, the model contains a 3D space system of coordinates and the values of x,y,z for every atom. This coordinate system is inherent to the model. If you load several models, each one brings its own coordinates, so you will usually see both models positioned very far apart, or sometimes overlapping.

Some commands, however, refer to a 2D space, the projection that the observer sees; these are the "screen coordinates".

Jmol uses the 3D coordinates for nearly all the operations. Note also that, when the model is rotated or translated (either by mouse action or by commands) the coordinate system and axes move together with the model. That is, position of the model in the 3D coordinate system is always the same; it's just the viewpoint that changes (and, accordingly, the screen coordinates do change with any rotation, translation or zoom).

=== Commands that use each coordinate system ===
==== 3D coordinates ====
<code>label</code>
:Labels are attached to individual atoms, therefore they are linked to the x,y,z coordinates. [{{ScriptingDoc}}#label Command syntax] 

<code>measure</code>
:Measurements are also attached to 2, 3 or 4 atoms and so work with the 3D x,y,z coordinates. [{{ScriptingDoc}}#measure Command syntax] 

<code>set echo</code> (3D variety)
:The special syntax for the echo command that provides 3D coordinates of a point to which the echo will be attached (and hence the echo will rotate and translate with the model). [{{ScriptingDoc}}#setecho Command syntax] 
: Example: <code>set echo id myFirstEcho {1.2 -4.0 1.1}; echo This is the position in 3D;</code>

==== Screen coordinates ====
<code>set echo</code> (2D variety)
:The more standard syntax of the echo command positions text with reference to the screen 2D space (hence the text does not move when the model is rotated or translated). [{{ScriptingDoc}}#setecho Command syntax] 
: Examples: 
:: <code>set echo top center; echo This is a title;</code>
:: <code>set echo id mySecondEcho 100 50; echo This is at 100,50 pixels;</code>
:: <code>set echo id my3rdEcho 10% 90%; echo This is near top left;</code>

=== Retrieving 3D coordinates ===
When a model file is loaded, the position of the origin and the orientation of the x,y,z axes are usually:
* origin at the center of the Jmol screen
* X axis horizontally to the right
* Y axis vertically upwards
* Z axis normal to the screen and to the front (towards the observer)
This may be different if the file contains some orientation instructions.

The command <code>axes on</code> will let you check those.

Examples of how to check the coordinates of an atom:
(<code>p1</code> is a variable used to hold the values and <code>print</code> allows to see its value)
<pre>
p1 = {atomNo=6}.xyz;
print p1.x;
print p1.y;
print p1.z;

p1 = {atomNo=6}.x;
print p1;
p1 = {atomNo=6}.y;
print p1;
p1 = {atomNo=6}.z;
print p1;
</pre>

=== Retrieving screen coordinates ===
Screen coordinates sx,sy,sz are defined as:
* sx from the left border
* sy from the bottom border
* sz from the front (small sz for positions at the front, near the observer; large sz for positions at the rear, far from the observer)
<pre>
p2 = {atomNo=6}.sx;
print p2;
p2 = {atomNo=6}.sy;
print p2;
p2 = {atomNo=6}.sz;
print p2;
</pre>

=== Converting between 3D coordinates and screen coordinates ===
This gives the screen coordinates {sx, sy, sz} corresponding to the 3D coordinates {x, y, z}:
 point({x,y,z}, true);
Examples of use:
<pre>
p3 = point( {atomNo=6}, true)
print p3.x;  // same as print {atomNo=6}.sx;
print p3.y;  // same as print {atomNo=6}.sy;

p3 = point( {4.65, -9.80, 1.21}, true)
print p3.x;
print p3.y;
</pre>

And this does the opposite conversion: gives the 3D coordinates {x, y, z} corresponding to the screen coordinates {sx, sy, sz}:
 point({sx,sy,sz}, false);
Example of use:
<pre>
p4 = point( {124, -230, 5000}, false)
print p4.x;
print p4.y;
</pre>