Skip to content

Latest commit

 

History

History
188 lines (145 loc) · 7.49 KB

README.md

File metadata and controls

188 lines (145 loc) · 7.49 KB
Raw

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

Additional Credits

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' } }

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

  • 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

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