PlanetMaker User Guide
Get to know PlanetMaker and get the most out of it to make the perfect planets
Quickly get started using PlanetMaker
Requirements
PlanetMaker is a graphics intensive application which makes use of the latest WebGL technology available in some modern browsers. It requires the use
of the latest versions of either
Google Chrome
or
Mozilla Firefox (though it has been reported to work in Safari) and have accelerated graphics
capabilities.
Interface
Hide Controls
Allows for hiding of the on-screen control elements along with the page title and other items.
A link will appear in the top right labels 'Show Controls' which will redisplay the hidden controls.
GUI Transparency
Adjust the transparency of the control elements for increases visibility of the scene.
PlanetMaker uses mouse and keyboard based navigation controls, similar to those in Google Earth.
Rotating
Rotate the scene by left-clicking and dragging with the mouse
Pitch/Roll
Control the pitch & roll of the scene by holding down shift while left-clicking and
dragging with the mouse.
Panning
Pan the scene (offsetting the planet from the center, similar to turning your head away from
the object of focus) by holding down Ctrl while left-clicking and dragging with the mouse.
Zooming
Zoom either with the scroll-wheel or by right-clicking and dragging the mouse up or down.
Scene options control general effects such as source image resolutions, lighting, and shadows.
Texture Resolution
Controls the resolution (detail level) of the source images. Higher values mean enhanced detail, but
are subject to memory and GPU limits.
Lighting Type
Switch between directional and point lighting. Directional simulates a planet which receives
most of it's light from a local star. Point lighting makes the light emit from the planet itself.
Sunlight Direction
The direction from which "directional" light will flow, in degrees.
Date/Time Sunlight
Automatically determine sunlight direction using the "Sunlight Date" option.
Sunlight Date (UTC)
Date to use when determining sunlight direction if "Date/Time Sunlight" option is checked, based on
Coordinated Universal Time (UTC).
This is an approximation, true sunlight azimuth & declination may differ some.
Enable Shadows
Enable shadows on objects.
Shadow Darkness
Darkness of shadows on objects (amount of blocked sunlight).
SceneScript Editor
Open the
SceneScript editor dialog.
Reset
Reload the page and set the model back to it's original state.
Planet Gallery
View a list of example planets.
Surface options control the planet itself and its physical properties.
Texture
Select the base texture for the planet surface.
Set Custom Texture
Open the
Custom Texture dialog.
Hue/Saturation/Lightness
Modify the surface color by applying HSL adjustments. By default, the
saturation is at the minimum so no color shading is applied.
Color Mode
Invert and/or force greyscale color transformations on the surface image.
Detail Level
Adjust the level of detail with which surface features are shaded using normal mapping.
Elevation Scale
Adjust the scale with which elevations are derived from the height map.
Flattening
Adjust the level of planetary
flattening.
Axial Tilt
Adjust the
axial tilt of the planet, in degrees.
Shininess
Adjust the shininess of the surface. Higher values result in a more focused reflection.
The minimum value of 0 results in a uniform, matte, distribution of light.
Specular Light
The intensity of light that contributes to the shininess of the surface.
Diffuse Wrap Around
Degree of diffuse (normal) lighting which is visible on surfaces facing away
from the light source.
Ambient Light
Intensity of scattered, non-directional light present in the surface.
Emissive Light
Intensity of light being emitted by the planet.
City Lights
Enable the visibility of city lights in low-light portions of the planet.
City Light Level
Intensity of visibility of city lights.
Clouds options control the clouds and their physical properties such as texture,
thickness, altitude, and coloring.
Display Clouds
Enable or disable the display of the cloud layer.
Texture
Select the base texture for the planets clouds.
Hue/Saturation/Lightness
Modify the cloud color by applying HSL adjustments. By default, the
saturation is at the minimum so no color shading is applied.
Detail Level
Adjust the level of detail with which surface features are shaded using normal mapping.
Altitude
Adjust the altitude above the surface in which the clouds reside (Cloud base/Ceiling).
Thickness
Adjust the scale with which elevations are derived from the height map.
Opacity
Adjust the opacity, or transparency, of the cloud layer.
Cast Shadows
Enable or disable cloud shadows on the surface.
Shadow Level
Adjust the amount of light blocked by the clouds in the surface shadows.
Specular Light
The intensity of light that contributes to the shininess of the clouds.
Ambient Light
Intensity of scattered, non-directional light present in the clouds.
A star, local to your planet, which is the source of light.
Display Local Star
Enable or disable the visibility of the local star. When enabled, the camera must
be pointed towards the light source for the star to be visible.
Size
Adjust the size of the local star.
Texture
Select the image used to represent the local star.
Color
Adjust the color emitted by the star.
Planet Lighting
Toggle whether the color of the light reaching the planet is affected by
that of the local star.
Lens Flare
Enable or disable lens flare when the local star is in view.
Control the altitude, density and color of the planet's atmosphere
Display Atmosphere
Toggle the visibility of the planets atmosphere.
Color
Adjust the color of the atmosphere.
Altitude
Adjust the high (altitude) of the atmospheric halo.
Density
Adjusts the density of the atmosphere as it approaches the horizon.
Display and adjust the appearance, size, and coloring of a planetary ring system
Display Rings
Toggle the visibility of a planetary ring system.
Hue/Saturation/Lightness
Modify the ring color by applying HSL adjustments. By default, the
saturation is at the minimum so no color shading is applied.
Inner Radius
Adjust the inner radius of the ring system.
Outter Radius
Adjust the outter radius of the ring system. This must be greater than the inner
radius for the rings to be visible.
Angle
Adjust the angle, or
inclination, in degrees that the rings move along
Opacity
Adjust the opacity, or transparency, of the ring layer.
Change and customize the background
Type
Switch between background types. The default is "Stars" which provides a simulated
stellar neighborhood with a configurable density. "Image" allows for the use
of image textures as backgrounds.
Image
Select the image texture to use as the background when the type is set to "Image".
Projection
Toggle the image background projection between a static flat display and a wrapped "spherical"
projection.
Fit Type
Adjusts how a flat background image is fit to the scene.
Set Custom Texture
Open the
Custom Texture dialog.
Star Quantity
Adjust the amount of stars visible in the background when the type is set to "Stars".
Add moons and control their physical properties and locations
Adding a Moon
Create Moon
Adds a moon to the scene and creates a configuration box.
Adjusting Moon
Display Moon
Toggle the visibility of the moon object.
Delete Moon
Deletes the moon from the scene.
Texture
Select the base texture for the moon surface.
Hue/Saturation/Lightness
Modify the surface color by applying HSL adjustments. By default, the
saturation is at the minimum so no color shading is applied.
Color Mode
Invert and/or force greyscale color transformations on the surface image.
Detail Level
Adjust the level of detail with which surface features are shaded using normal mapping.
Elevation Scale
Adjust the scale with which elevations are derived from the height map.
Shininess
Adjust the shininess of the surface. Higher values result in a more focused reflection.
The minimum value of 0 results in a uniform, matte, distribution of light.
Specular Light
The intensity of light that contributes to the shininess of the surface.
Ambient Light
Intensity of scattered, non-directional light present in the surface.
Emissive Light
Intensity of light being emitted by the planet.
Size
Adjust the size of the moon
Distance
Adjust the distance of the moon from the center of the planet (semimajor axis)
Rotation
The rotation of the moon relative to the planet, in degrees.
Orbit Position
The angular position of the moon in it's orbit (true anomaly). Currently, moons are positioned
along a purely circular orbit.
Apply and customize dynamic effects
Enable Blur
todo
Blur Amount
todo
Enable Bloom
todo
Bloom Strength
todo
Enable Bleach
todo
Bleach Amount
todo
Enable Sepia
todo
Sepia Amount
todo
Enable Film
todo
Noise Intensity
todo
Scanlines Intensity
todo
Scanlines Count
todo
Grayscale
todo
Upload and apply your own custom texture images
Textures for use as a planet surface are recommended to be 2x1 (equirectangular) aspect
ratio such as 1024x512, 2048x1024, or 4096x2048. Note that the size may be limited by your
system and browser memory and graphics capabilities.
todo
SceneScript provides a basic API for creating deep customizations to the
PlanetMaker scene. Also exposed are the PlanetMaker internals, Three.js, and jQuery APIs.
Script Data Objects
planet
This is the primary PlanetMaker engine which provides access into the internals of the application.
config
The primary configuration map used by PlanetMaker.
context
A map of application data including configurations and scene objects.
Script Callbacks
onFrame(planet, config, context)
Called prior to the scene object update routine which is invoked before each frame is rendered
- planet: The primary PlanetMaker scene container
- config: Scene configuration
- context: THREE.js and environmental context objects
- returns: True if changes are made to the scene objects that will need to be addressed by their internal update methods.
Template:
function onFrame(planet, config, context) {
return false;
}
onRender(planet, config, context)
Called prior the the scene being rendered to the screen.
- planet: The primary PlanetMaker scene container
- config: Scene configuration
- context: THREE.js and environmental context objects
Template:
function onRender(planet, config, context) {
}
onScriptInitialize(planet, config, context)
Called within renderer the first time it encounters this script instance to allow in-context initialization.
- planet: The primary PlanetMaker scene container
- config: Scene configuration
- context: THREE.js and environmental context objects
- returns: True if changes are made to the scene objects that will need to be addressed by their internal update methods.
Template:
function onScriptInitialize(planet, config, context) {
return false;
}
onScriptDestroy(planet, config, context)
Called within renderer if/when the script instance is replaced by a new version
(such as when 'Apply Changes' is clicked). Allows for clean-up of any resources
which may be specific to the script instance.
- planet: The primary PlanetMaker scene container
- config: Scene configuration
- context: THREE.js and environmental context objects
- returns: True if changes are made to the scene objects that will need to be addressed by their internal update methods.
Template:
function onScriptDestroy(planet, config, context) {
return false;
}
Methods
radians( degrees ) : number
Converts degrees to radians. Shortcut for
degrees * (Math.PI / 180)
.
degrees( radians ) : number
Converts radians to degrees. Shortcut for
radians * (180 / Math.PI)
.
rotatePlanet( rotationInDegrees )
Sets the rotation of the planet in degrees. This is an absolute rotation and not incremental to the previous rotation.
rotateScene( rotationInDegrees )
Sets the rotation of the scene in degrees. This is an absolute rotation and not incremental to the previous rotation.
rotateMoon( moonIndex, rotationInDegrees )
Sets the rotation of the moon at 'moonIndex' in degrees. This is an absolute rotation and not incremental to the previous rotation.
rotateMoons( rotationInDegrees|Array )
Sets the rotation of all moons in degrees. The parameter can be either numerical, which is applied to all moons, or an array
with a rotation value for each moon.
Using a Single Rotation Value:
rotateMoons(90); // Sets rotation of all moons to 90°
Using an Array With Rotation Values:
rotateMoons([45, 90, 135]); // Applies rotations to first three moons in scene
advanceMoonOrbit( moonIndex, rotationInDegrees )
Advances the moons orbital position in degrees. This value is incremental to the last call and positive values
will move the moon counter-clockwise as viewed from above.
advanceMoonOrbits( rotationInDegrees|Array )
Advances all moons orbital positions in degrees. This value is incremental to the last call and positive values
will move the moon counter-clockwise as viewed from above. The parameter can be either numerical, which is applied to
all moons, or an array with a rotation value for each moon.
Using a Single Rotation Value:
advanceMoonOrbits(90); // Sets orbit movement of all moons to 90°
Using an Array With Rotation Values:
advanceMoonOrbits([45, 90, 135]); // Applies orbit movement to first three moons in scene
addToPrimaryScene( object )
Adds a
KMG.BaseObject
derived object to the primary (foreground) scene.
Example:
var belt = new KMG.BasicAsteroidBeltObject(context, {
innerRadius : 260,
outterRadius : 400
});
addToPrimaryScene(belt);
addToSecondaryScene( object )
Adds a
KMG.BaseObject
derived object to the secondary (background) scene.
Examples
Create Several Moons:
function onScriptInitialize(planet, config, context) {
planet.addMoon({moonDistance : 1.0, moonScale : 0.25});
planet.addMoon({moonDistance : 1.5, moonScale : 0.25});
planet.addMoon({moonDistance : 2.0, moonScale : 0.25});
planet.addMoon({moonDistance : 2.5, moonScale : 0.25});
planet.addMoon({moonDistance : 3.0, moonScale : 0.25});
planet.addMoon({moonDistance : 3.5, moonScale : 0.25});
return true;
}
Adding an Asteroid Belt:
function onScriptInitialize(planet, config, context) {
var belt = new KMG.BasicAsteroidBeltObject(context, {
innerRadius : 260,
outterRadius : 400
});
addToPrimaryScene(belt);
return true;
}
Adding a Moon with an Asteroid Belt:
function onScriptInitialize(planet, config, context) {
var moon = planet.addMoon({moonDistance : 1.0, moonScale : 0.25});
var belt = new KMG.BasicAsteroidBeltObject(context, {
innerRadius : 100,
outterRadius : 160,
targetObject : moon.object
});
addToPrimaryScene(belt);
return true;
}
Add a Rotator to the Planet:
function onScriptInitialize(planet, config, context) {
var rotator = new KMG.ObjectRotator(context,
[context.surfaceObject, context.cloudObject],
1.0 // Rotation speed, degrees per tick
);
rotator.start();
return true;
}
Adding a Rotating Moon:
function onScriptInitialize(planet, config, context) {
var moon = planet.addMoon({moonDistance : 1.0, moonScale : 1.0});
var rotator = new KMG.ObjectRotator(context,
moon.object, // Object being rotated
1.0 // Rotation speed, degrees per tick
);
rotator.start();
return true;
}
Adding an Orbiting Moon:
function onScriptInitialize(planet, config, context) {
var moon = planet.addMoon({moonScale : 1.0});
var orbiter = new KMG.BasicOrbiter(context,
moon.object, // Object doing the orbiting
1.0, // Orbit distance (semimajor axis)
1.0 // Orbit speed
);
return true;
}
Stacking Animators - Rotating and Orbiting Moon:
function onScriptInitialize(planet, config, context) {
var moon = planet.addMoon({moonScale : 1.0});
var rotator = new KMG.ObjectRotator(context,
moon.object, // Object being rotated
1.0 // Rotation speed, degrees per tick
);
rotator.start();
var orbiter = new KMG.BasicOrbiter(context,
moon.object, // Object doing the orbiting
1.0, // Orbit distance (semimajor axis)
1.0 // Orbit speed
);
return true;
}
Add Moon With Basic Orbit Line:
function onScriptInitialize(planet, config, context) {
var moon = planet.addMoon({moonScale : 1.0, moonDistance : 1.0});
var orbit = new KMG.BasicOrbitPathLine(context, {distance : 1.0});
addToPrimaryScene(orbit);
return true;
}
Add a moon on Pluto's Orbit:
function onScriptInitialize(planet, config, context) {
var moon = planet.addMoon({moonScale : 1.0});
var orbiter = new KMG.EllipticalOrbiter(context,
moon.object,
30.0, // Orbit multiplier (scale)
1.0, // Orbit speed
KMG.OrbitDefinitions.pluto // Orbital properties
);
var orbitConfig = KMG.Util.clone(KMG.OrbitDefinitions.pluto);
orbitConfig.scale = 30;
orbitConfig.segments = 256;
addToPrimaryScene(new KMG.OrbitPathLine(context, orbitConfig));
return true;
}
Solar System Animation:
function onScriptInitialize(engine, config, context) {
config.lightingType = "Point";
config.lensFlareEnabled = false;
config.displayLocalStar = false;
config.displayClouds = false;
config.displayAtmosphere = false;
config.scaleSurface = .02;
config.texture = "Sun";
config.ambientIntensity = 255.0;
config.emissiveIntensity = 255.0;
config.enableCityLights = false;
config.shininess = 0;
config.flattening = 0;
var sunRotator = new KMG.ObjectRotator(engine.context, engine.context.surfaceObject, 3.0);
sunRotator.start();
var tex = {
name : "",
texture : "",
bumpMap : "",
normalMap : "",
specularMap : "",
enabled : true
};
KMG.textures.push(KMG.Util.extend({ name : "mercury", texture : "/img/planets_small/mercury.jpg"}, tex));
KMG.textures.push(KMG.Util.extend({ name : "venus", texture : "/img/planets_small/venus.jpg"}, tex));
KMG.textures.push(KMG.Util.extend({ name : "earth", texture : "/img/planets_small/earth.jpg"}, tex));
KMG.textures.push(KMG.Util.extend({ name : "mars", texture : "/img/planets_small/mars.jpg"}, tex));
KMG.textures.push(KMG.Util.extend({ name : "jupiter", texture : "/img/planets_small/jupiter.jpg"}, tex));
KMG.textures.push(KMG.Util.extend({ name : "saturn", texture : "/img/planets_small/saturn.jpg"}, tex));
KMG.textures.push(KMG.Util.extend({ name : "uranus", texture : "/img/planets_small/uranus.jpg"}, tex));
KMG.textures.push(KMG.Util.extend({ name : "neptune", texture : "/img/planets_small/neptune.jpg"}, tex));
KMG.textures.push(KMG.Util.extend({ name : "pluto", texture : "/img/planets_small/pluto.jpg"}, tex));
function addOrbitingPlanet(orbitConfig, objectScale, texName, showRing) {
var scale = 35;
var planetConfig = KMG.Util.clone(orbitConfig);
planetConfig.scale = scale;
planetConfig.segments = 256;
planetConfig.opacity = 0.4;
addToPrimaryScene(new KMG.OrbitPathLine(engine.context, planetConfig));
var planet = engine.addMoon({moonScale : objectScale, moonTexture : texName});
var orbiter = new KMG.EllipticalOrbiter(engine.context, planet.object, scale, 10000000.0, planetConfig);
var rotator = new KMG.ObjectRotator(engine.context, planet.object, 3.0);
rotator.start();
if (showRing) {
var ring = new KMG.RingObject(context, {
ringInnerRadius : 90 * objectScale,
ringOutterRadius : 130 * objectScale,
targetObject : planet.object,
displayRing : true
});
addToPrimaryScene(ring);
var orbiter = new KMG.EllipticalOrbiter(engine.context, ring, scale, 10000000.0, planetConfig);
}
}
var planetScale = .05;
addOrbitingPlanet(KMG.OrbitDefinitions.mercury, planetScale * .2, "mercury");
addOrbitingPlanet(KMG.OrbitDefinitions.venus, planetScale * .4, "venus");
addOrbitingPlanet(KMG.OrbitDefinitions.earth, planetScale * .4, "earth");
addOrbitingPlanet(KMG.OrbitDefinitions.mars, planetScale * .25, "mars");
addOrbitingPlanet(KMG.OrbitDefinitions.jupiter, planetScale, "jupiter");
addOrbitingPlanet(KMG.OrbitDefinitions.saturn, planetScale, "saturn", true);
addOrbitingPlanet(KMG.OrbitDefinitions.neptune, planetScale, "neptune");
addOrbitingPlanet(KMG.OrbitDefinitions.uranus, planetScale, "uranus");
addOrbitingPlanet(KMG.OrbitDefinitions.pluto, planetScale, "pluto");
var belt = new KMG.BasicAsteroidBeltObject(context, {
innerRadius : 100,
outterRadius : 160,
color : 0xC0C0C0,
size : 0.7
});
addToPrimaryScene(belt);
return true;
}
People and organizations that created and/or own some of the resources used in PlanetMaker.
List of changes and modifications to PlanetMaker
- October 30, 2013:
- Rendering improvements
- Added scripting via SceneScript
- New User Guide
- New Postprocessing Effects
- New View Controls (like Google Earth)
- User Interface Improvements
- New Textures (Venus, etc...)
- July 29, 2013:
- Improved atmosphere
- New textures (A gas giant, banded clounds, a ring, & the Sun)
- Redesigned custom texture dialog
- Texture color modes (greyscale, inverted)
- Multiple moons
- Point light option (Main object is the one emitting light)
- Improved background stars
- Bug fixes and misc tweaks
- July 5, 2013: Fixed alphatest for ring opacity, Moon texture load defect
- July 3, 2013: Added ability to use a WebCam for textures
- June 27, 2013: Rolled out a new User Interface.
- June 21, 2013: HSL levels for surface and moon textures, some sample libnoise textures, and a gas giant texture.
- June 18, 2013: Fixed shadow bug
- June 17, 2013: Improved cloud shading
- June 12, 2013: Ability to adjust cloud shadow level (darkness), better city light adjustment, atmosphere improvements
- June 11, 2013: Adding a moon, planet flatting, misc fixes
- June 6, 2013: Ring opacity level
- June 5, 2013: Custom texture shading fix; Emissive lighting
- June 4, 2013: Ability to change local star texture and color
- June 3, 2013: Ability to switch between flat & spherical background images; Some extra error handling
- June 2, 2013: Added a local star
- May 31, 2013: Added ability to select or upload background images.
- May 30, 2013: Added ability to change the quantity of stars, enhanced "about" dialog.
- May 29, 2013: Added new surface textures for Earth & Jupiter