jquery.earth-3d
JQuery plugin that allows you to draw a beautiful 3d spinning earth on canvas. Take a look at the demo: http://sdrdis.github.com/jquery.earth-3d/
Description
Based on the amazing sphere.js plugin of Sam Hasler, jquery.earth3d.js is an open source jquery ui plugin which will allow you to emulate a 3d earth (or any planet actually) on canvas. I also added some functionalities I needed for my pet project.
Here are the main functionality provided so far:
- Change the map texture (you can change it to mars for example), along with the tiling
- Change the rotation axis (tilt, turn)
- Change the size
- Change the default rotation speed
- Smooth mouse drag: you can rotate the earth with your mouse, it will smoothly return to the normal speed
- Render locations by indicating spherical coordinates
- Draw paths between these locations
- Draw and update flights following paths
- Location and flights are clickable and entirely customizable
- It works on mobile
Licence
jquery.earth3d.js is, as the sphere.js plugin, under MIT licence.
Authors
- Sebastien Drouyer - alias @sdrdis - for this jquery ui plugin
- Sam Hasler - alias @SamHasler - for the sphere.js plugin
Additional Credits
- Roger Cook and Don Shanosky for the plain icon, on thenounproject.
Known issues
I didn't do pure mathematics since a long time ago, and I didn't have a huge amount of time to make this plugin, so there are some known and urgent issues to resolve for jquery.earth-3d.js to become stable.
All problems locations can be found in the file jquery.earth-3d.js when you search for "WARNING". If you have an idea, don't hesitate to do a pull request :).
The main problems are:
-
I got the locations and paths to work only when the planet is not rotated. I had to create some horrible function, as _calibrated, to make this work. I tried different approaches, but failed each time (the problem might be coming from me :)).
-
Paths drawing are the main optimization issue (you can easily notify it on the demo). For the moment it is drawn on canvas, but I wonder if we could gain some CPU by instead using SVG or the DOM.
Areas for improvement
Of course, if anybody has a suggestion, don't hesitate to use github issues :).
Here are some possible improvements:
- Defining a starting position
- Make it possible to rotate around the globe as if we are in orbit
- For the moment, glows and shadows are designed on photoshop. I will soon post a tutorial on how to do it, but what could be awesome is to generate it on canvas, and defining light angle and intensity...
- Zoom support
- The code can always be cleaner, more optimized...
Documentation
Options:
-
texture: texture map used by the planet
-
sphere: rotation and size of the planet
-
defaultSpeed: default spinning speed of the planet
-
backToDefaultTime: time (in ms) to return by to default speed when planet is dragged
-
locations: locations to display on the planet:
- Each position must have a key, an alpha and delta position (or x and y if you want to display a static location). Any additional key can be reached via callbacks functions Example:
{ obj1: { alpha: Math.PI / 4, delta: 0, name: 'location 1' } }
- Each position must have a key, an alpha and delta position (or x and y if you want to display a static location). Any additional key can be reached via callbacks functions Example:
-
paths: paths and flights to display over the planet: Each path must have a key, an origin and a destination. The values are the location's key. You can, if you want to, define flights on these paths. Each flight has a key, a destination (the location's key) and a position. The position is the progress a fleet has made on its path. Any additional key can be reach via callbacks functions. Example:
{ path: { origin: 'obj1', destination: 'obj2', flights: { flight: { position: 0.25, destination: 'obj2', name: 'Flight 1' }, flight2: { position: 0.25, destination: 'obj1', name: 'Flight 2' } } } }
-
flightsCanvas: Dom element which is a canvas and where the flights and paths are drawn
-
dragElement: Dom element where we catch the mouse drag
-
locationsElement: Dom elements where the locations are drawn
-
flightsCanvasPosition: position of the flight canvas (can be use if you have some gap between your planet and your flights
-
pixelRadiusMultiplier: (TEMPORARY) used by the getSphereRadiusInPixel (see the functions)
-
onInitLocation: callback function which allows you to define what to do when the locations are initialized
- Parameters:
- location: location (coming from locations option)
- widget: earth3d widget object
- Parameters:
-
onShowLocation: callback function which allows you to define what to do when a location becomes visible (was behind the planet and is now in front of it)
- Parameters:
- location: location (coming from locations option)
- x: 2d left position
- y: 2d top position
- widget: earth3d widget object
- Parameters:
-
onRefreshLocation: callback function which allows you to define what to do when a location is refreshed (it moves)
- Parameters:
- location: location (coming from locations option)
- x: 2d left position
- y: 2d top position
- widget: earth3d widget object
- Parameters:
-
onHideLocation: callback function which allows you to define what to do when a location becomes invisible (was in front of the planet and is now behind it)
- Parameters:
- location: location (coming from locations option)
- x: 2d left position
- y: 2d top position
- widget: earth3d widget object
- Parameters:
-
onInitFlight: callback function which allows you to define what to do when the flights are initialized
- Parameters:
- flight: flight (coming from flights option)
- widget: earth3d widget object
- Parameters:
-
onShowFlight: callback function which allows you to define what to do when a flight becomes visible (was behind the planet and is now in front of it)
- Parameters:
- flight: flight (coming from flights option)
- widget: earth3d widget object
- Parameters:
-
onRefreshFlight: callback function which allows you to define what to do when a flight is refreshed (it moves)
- Parameters:
- flight: flight (coming from flights option)
- x: 2d left position
- y: 2d top position
- widget: earth3d widget object
- Parameters:
-
onHideFlight: callback function which allows you to define what to do when a flight becomes invisible (was in front of the planet and is now behind it)
- Parameters:
- flight: flight (coming from flights option)
- widget: earth3d widget object
- Parameters:
Functions
-
getSphereRadiusInPixel: function which allows you to get the sphere radius in pixel /!| WARNING: this function needs to be refactored, since I didn't find out (my maths courses are far away) how to get the exact value. I did a basic linear regression, but it is not exact, and you will have to change the pixelRadiusMultiplier option to get the correct value
-
destroy: use this function when you want to destroy the object. It will throw a cancel animation frame, so the CPU won't be used anymore.
-
changePaths: use this function when you want to update paths and flights (options on widget) it will add the callback functions support