Oolite coordinate systems

Oolite Coordinate system

By definition the witchpoint is the origin of the system with coordinate [0,0,0], and the buoy is placed at the origin. The main planet is placed on the Z-axis at a distance of about 10 to 14 times the main planet radius from the origin. (This is roughly at 300 000 to 900 000 meters from the origin). The sun is placed at a random direction from the planet, around 20 planetary radii from the planet, but never too close to the witchpoint-planet line.

legacy_addShipAt systems

In most situations the scripter is not interested in the exact coordinates of a point but just the position relative to other system objects. For this reason offers Oolite a whole series of different coordinate systems for the scripter. These are all characterised with a 3-character code to be used in the various legacy_addShip functions.

first letter

The first letter indicates the feature that is the origin of the coordinate system.

w => witchpoint
s => sun
p => planet

second letter

The next letter indicates the feature on the 'z' axis of the coordinate system.

w => witchpoint
s => sun
p => planet

Then the 'y' axis of the system is normal to the plane formed by the planet, sun and witchpoint. And the 'x' axis of the system is normal to the y and z axes. So:

ps:  z axis = (planet -> sun)  y axis = normal to (planet - sun - witchpoint)  x axis = normal to y and z axes
pw:  z axis = (planet -> witchpoint)  y axis = normal to (planet - witchpoint - sun)  x axis = normal to y and z axes
sp:  z axis = (sun -> planet)  y axis = normal to (sun - planet - witchpoint)  x axis = normal to y and z axes
sw:  z axis = (sun -> witchpoint)  y axis = normal to (sun - witchpoint - planet)  x axis = normal to y and z axes
wp:  z axis = (witchpoint -> planet)  y axis = normal to (witchpoint - planet - sun)  x axis = normal to y and z axes
ws:  z axis = (witchpoint -> sun)  y axis = normal to (witchpoint - sun - planet)  x axis = normal to y and z axes

third letter

The third letter denotes the units used:

m:  meters
p:  planetary radii
s:  solar radii
u:  distance between first two features indicated from 0 to 1. Negative values or values greater that 1 are allowed. 

(eg. spu means that u = distance from sun to the planet)

in interstellar space (== no sun) coordinates are absolute irrespective of the system used

absolute coordinates

When you use the code "abs" as coordinate system, than there is no transformation and you can use coordinates in Oolite's internal coordinate system. For more in depth position calculations this native system will be the most important system.

With the Vector3D.interpolate method you can create your own coordinate system. When you add a custom station in a system and you want to populate the spacelane between this station and the main station you can use:

coordinate = Vector3D.interpolate(system.mainStation.position, cutomStation.position, fraction)

This results in an absolute coordinate between the two positions. Fraction runs from 0 to 1, representing the lane and values outside this range are also allowed. By using:

system.legacy_addShipsAt("role", number, "abs", coordinate)

you add the ship at exactly that calculated spot.

legacy_addSystemShips

For this one you don't need to specify a coordinate system. It uses the line witchpoint to main station as its baseline. Just be aware that this line is not the same as witchpoint<-->planet. The more close to the planet the more they start to deviate from each other. Players flying straight from witchpoint to the station will find ships sooner on this route while players that first fly to the planet will find ships sooner when added on the "wpu" route. Take note that the populator adds the ships on the "wpu" route.

return