spinning ball

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.

Initialization

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 minLongitude and maxLongitude are 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)

API

Initialization returns an object with the following properties and methods:

• view: Pointer to a view object as generated by the initView method 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 units specified 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 .cameraPos() and .cursorPos().

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.