- Add a container HTML element e.g. <div id="myearth"></div>
- Load miniature.earth.js (or miniature.earth.core.js)
- Initiate and setup your earth. See Minimal Example, Asynchronous Integration or Preload & Fallback
miniature.earth.js bundles everything you need to start in one file.
miniature.earth.core.js is a slimmed-down version:
- Without SVG map, so you need to provide a mapImage.
- Without 3D marker meshes but you can load custom meshes if you need 3D markers.
You can use your favorite map service to get the lat/lng geo coordinates for a specific address. If you use Google Maps you can search an address and extract the coordinates right from your browsers URL:
https://www.google.com/maps/place/New+York+City,+USA/@40.6918636,-74.0965785,11.25z/data=...
The coordinates as JavaScript object: { lat: 40.6918636, lng: -74.0965785 }Save your mesh as Wavefront (.obj) file in an uncompressed text format.
- Apply modifiers, triangulate faces
- Only meshes are supported, all other 3D features are ignored (like materials, UVs, ...)
- The file can contain multiple objects/meshes at top level
- The object/mesh names should only consist of letters and numbers
- If you open your .obj file in a text editor it should look like this:
o MyMeshName
v 0.625 0.0 0.0
v 0.562 0.108 0.0
...
f 7 2 1
f 2 9 3
...
Example: Custom Marker Meshes
Tool: Get .obj File as Minified String
You can draw on the map to extent it and make little modifications. See Drawing on the Map
In src/map.svg you find the default map. You can make a copy, modify it and load it with the mapImage property.
Please note: the map* properties apply to the default map only, so set your styles and colors right in your custom svg.
You can use maps with equirectangular projection from other sources like:
- NASA satellite images
- Wikipedia vector maps
Some features do not work with the file: protocol due to browser security restrictions, for example loading images or custom markers. Please develop on a web server or install a local web server like XAMPP.
Images and custom markers must be loaded from the same domain.
See Object Types / Stacking and Transparent Rendering
If your earth or markers are cut off, you will need to reduce the earth zoom so that your contents fit inside. You can increase the container size to view the earth on a larger scale.
If your earth looks blurry you can set a higher quality level. If you use large images/sprites you will need to increase the imageResolution.
Every browser has a JavaScript console integrated, check it for errors and warnings.
Reduce the complexity of your code and add functionality step by step.
Enable gzip compression on your web server to reduce the filesize of miniature.earth.js to about 260KB.
Support for Internet Explorer 11 is not enabled by default, so your fallback content will be displayed.
You can enable support for IE11 with some trade-offs:
- IE11 doesn't support SVG maps. You need to use a mapImage or provide a fallbackMapUrlIE11.
- IE11 doesn't support EarthInstance.mapHitTest and hitTest()
- Modules for advanced features: Clustering, Draggable, Input, MapDraw, Materials, ScrollSync, SliderSync, TextImage
- Added the Points object to efficiently represent many locations
- New CSS classes to style Overlays based on their position
- New property: EarthInstance.sunDirection
- Serveral improvements and changes to stacking, transparancy and occlusion. Please see the updated documentation.
- The auto rotation is now framerate independent.
- No more unwanted clicks are triggered after dragging.
- The values of lat/lng objects are now automatically converted to numbers.
- New method for objects: stopAllAnimations()
- New method: EarthInstance.hitTest()
- New method: EarthInstance.destroy()
- The default value of the hotspot property has been changed to false.
- The texture property has been extended and renamed to EarthInstance.mapImage.
- Bugfix: the Wordpress integration example failed with some webservers
- Added Images and Sprites
- Performance and render quality improvements
- In animation callbacks, this now refers to the animated element
- New examples