Simulate the position and motion of a camera above the Earth
Camera position above a spherical Earth is represented as a 3-vector of longitude, latitude, altitude, with associated angular and vertical velocities.
Accelerations can be induced by user interaction with the HTML div where the sphere will be rendered. Handled interactions include:
- Single-touch or mouse-click and drag motions (rotational acceleration)
- Two-touch pinches or scroll wheel rotations (vertical acceleration)
Velocities are damped, with weak damping when there are no active touches or clicks, to allow coasting. With an active touch/click/zoom, the damping constant is chosen for critical damping of the relevant induced spring force, to avoid any oscillation.
Note that the camera and the spherical Earth as modeled by spinning-ball are both purely conceptual. To display what would be seen by the camera, a separate renderer is required. See the example for a demo with a simple D3 renderer.
A spinning-ball instance can be initialized as follows:
import * as spinningBall from 'spinning-ball'; const ball = spinningBall.init(parameters);
The supplied parameters object has the following properties:
display(REQUIRED): An HTML element where the globe will be represented, and where the user's client will generate interaction events
units: Specify "degrees" or "radians" as the units of any supplied or returned longitude and latitude coordinates. Default: "degrees"
position: The initial position of the camera. Longitude and latitude must be in the specified units. Altitude must be in kilometers, and between minAltitude and maxAltitude. Default:
[0.0, 0.0, 4 * earthRadius]where
earthRadius == 6371.0
minAltitude: The minimum altitude of the camera, in kilometers. Default:
0.0001 * earthRadius
maxAltitude: The maximum altitude of the camera, in kilometers. Default:
8.0 * earthRadius
minLongitude: The minimum longitude of the camera, in the specified units. Default: -180 degrees (or -PI radians)
maxLongitude: The maximum longitude of the camera, in the specified units. Default: +180 degrees (or +PI radians). Note: if both
maxLongitudeare set to their defaults, the globe can be spun freely (it will not stop at the antimeridian)
minLatitude: The minimum latitude of the camera, in the specified units. Default: -90 degrees (or -PI / 2 radians)
maxLatitude: The maximum latitude of the camera, in the specified units. Default: +90 degrees (or +PI / 2 radians)
Initialization returns an object with the following properties and methods:
view: Pointer to a view object as generated by the
initViewmethod of yawgl. This can compute ray parameters at a point on the display
radius(): Returns the (floating point) radius of the sphere, in kilometers
project(xy, geodetic): Projects a given position to the [x,y] pair of display pixel coordinates where that position would be rendered
cameraPos(): Returns the current position of the camera
cursorPos(): Returns the position that would be rendered at the current screen position of the cursor
camMoving(): Returns a (Boolean) flag indicating whether the camera is moving
isOnScene(): Returns a (Boolean) flag indicating whether a ray shot from the current cursor position would intersect the globe
wasTapped(): Returns a (Boolean) flag indicating whether the globe has been tapped or clicked since the last update
cursorChanged(): Returns a (Boolean) flag indicating whether there has been any change in the position or status of the cursor relative to the globe
update(time): Updates the position and velocity of the camera, taking into account any current velocities, and computing new accelerations induced by mouse or touch interactions.
- Input time (floating point) is the current time in seconds. If using requestAnimationFrame, its argument should be multiplied by 0.001
- Return value is a flag indicating whether the display should be re-rendered, due to motion of the globe or resizing of the display
flyTo(position): Starts an animated flight that moves the camera to the provided position. The supplied position MUST be in the
unitsspecified on initialization, and within the specified bounds on longitude, latitude, and altitude. Note: the flight will be stepped through on subsequent calls to
.update, and canceled by any subsequent click/touch action.
Coordinate convention for positions on the globe
spinning-ball represents positions on the globe as 3-element arrays, of [longitude, latitude, altitude]. Longitude and latitude are in the units specified on initialization. Altitude is in kilometers.
This convention is assumed for the initial camera
position (on initialization)
and for the second argument of the API
.project method. It is also the format
of the values returned by
Notes about the code
Some functions include math for an ellipsoid, with different values for the polar and equatorial radius. However, the two radii MUST be kept equal for now, until the remaining functions are updated to handle a non-spherical Earth.