Quick Start

The Desmos Geometry tool provides a beautiful and simple way to incorporate constructive geometry into your web page or web app. Here's how to create an interactive dynamic geometry experience in just a few lines of code:

Step 1: include our secure JavaScript file:

<script src="https://www.desmos.com/api/v1.0/geometry.js?apiKey=dcb31709b452b1cf9dc26972add0fda6"></script>

Step 2: add an an element to the page:

<div id="geometry" style="width: 600px; height: 400px;"></div>

Step 3: add the following lines of JavaScript:

<script>
  var elt = document.getElementById('geometry');
  var geometry = Desmos.Geometry(elt);
</script>

Step 4: Enjoy:

Preparing for production: In this example, we used the demo API key dcb31709b452b1cf9dc26972add0fda6. For production use, you should obtain your own API key and supply it as the apiKey parameter in the script url in step 1.

Creating a new Instance

The basic structure of the API is an embeddable Geometry instance, which is the page element that will display your geometry board.

Constructor

constructor Geometry(element, [options])

Creates a Geometry object to control the embedded board in the DOM element specified by element.

It is possible to create a Geometry instance outside of the DOM and call methods on the returned object, but the view will not be created until element is inserted into the DOM.

Note: for every instantiated Geometry instance, we run a small set of computations on every frame in order to reliably detect when the instance is added to the DOM, removed from it, show, hidden, or resized. This could, theoretically, have performance and/or memory implications, although the effects are miniscule unless you instantiate many Geometry instances.

If you want to manage sizing yourself, you can instantiate with the API option {autosize: false}. In this case, you must call .resize() anytime that the instance is added to the DOM, removed from the DOM, or resized.

When you're done using a geometry instance, call .destroy() to remove all of our listeners.

Example:

var elt = document.getElementById('my-geometry');
var geometry = Desmos.Geometry(elt);

// Create a geometry instance outside of the DOM
var elt2 = document.createElement('div');
var geometry2 = Desmos.Geometry(elt2);

// Insert the element into the DOM and create the geometry view
document.body.appendChild(elt2);

// Destroy the root element and detach the geometry view
elt2.remove();
geometry2.destroy();

The object returned is a Desmos.Geometry object, which exposes methods for saving and loading board states.

options is an optional object that specifies features that should be included or excluded.

Geometry.destroy()

Free listeners and resources used by the geometry view.

Saving and Loading

Geometry.getState()

Returns a JavaScript object representing the current state of the geometry board. Used in conjunction with Geometry.setState to save and restore board states.

The return value of Geometry.getState may be serialized to a string using JSON.stringify.

Warning: States should be treated as opaque values. Manipulating states directly may produce a result that cannot be loaded by Geometry.setState.

Geometry.setState(obj, [options])

Geometry.setBlank([options])

Reset to a blank state. If an options object is present, the allowUndo property serves the same function as it does in Geometry.setState.

Examples:

// Save the current state of a geometry board
var state = geometry.getState();

// Use jQuery to post a state to your server for permanent storage
$.post('/myendpoint', JSON.stringify(state));

// Load a state into a geometry instance
geometry.setState(state);

// Reset to a blank state
geometry.setBlank();

See the saving and loading example for a live demo.

Geometry.setDefaultState(obj)

Add a default state and a reset button to allow the user to reset the tool to the default state after they have changed it.

Examples:

// Save the current state
var newDefaultState = geometry.getState();

// Set a new default state to match the current state
geometry.setDefaultState(newDefaultState);

For a working example see examples/geometry/default-state.html.

Geometry.screenshot([_opts_])

Returns an image of the current board in the form of a png data uri.

opts is an optional object with the following properties:

• opts.width Width of the screenshot in pixels. Defaults to current width of board in pixels.
• opts.height Height of the screenshot in pixels. Defaults to current height of board in pixels.
• opts.targetPixelRatio Oversampling factor. Defaults to 1. Larger values are useful for producing images that will look good on high pixel density (“retina”) screens. For example, setting opts.targetPixelRatio to 2 will return an image that is physically twice as wide and twice as tall as the dimensions specified by opts.width and opts.height, but that is designed to look good when displayed scaled down to the dimensions specified by opts.width and opts.height.

You can use the returned data uri directly in the src attribute of an image. To save the data as a traditional image file, you can parse the data and base64 decode it.

Examples:

// Capture a full size screenshot of the board
var fullsize = geometry.screenshot();

// Capture a double resolution screenshot of the board designed to
// be displayed at 200px by 200px
var thumbnail = geometry.screenshot({
  width: 200,
  height: 200,
  targetPixelRatio: 2
});

// Append the thumbnail image to the current page
var img = document.createElement('img');
// Note: if width and height are not set, the thumbnail
// would display at 400px by 400px since it was captured
// with targetPixelRatio: 2.
img.width = 200;
img.height = 200;
img.src = thumbnail;
document.body.appendChild(img);

See examples/geometry/screenshot.html for a working example.

Colors

The default color palette consists of the following colors:

Additionally, primitive object types are assigned a default color:

You may optionally provide a custom color palette for an instance (or override primitive defaults) by passing in a colorMap constructor option, which should define both an array of available colors and an object describing the primitive default colors. All strings must be valid hex colors.

colorMap: {
  colors: String[],
  defaults: {
    point: String,
    line: String,
    circle: String
  }
}

Example:

var customColorMap = {
  colors: ['#85144b','#39cccc','#01ff70','#b10dc9','#ff851B','#dddddd'],
  defaults: {
    point: '#85144b',
    line: '#39cccc',
    circle: '#01ff70'
  }
};
var elt = document.getElementById('geometry');
var geometry = Desmos.Geometry(elt, {colorMap: customColorMap});

See examples/geometry/custom-colors.html for a working example.

API Keys

In order to include the Desmos API in your page, you must supply an API key as a url parameter, like this:

<script src="https://www.desmos.com/api/v1.0/geometry.js?apiKey=dcb31709b452b1cf9dc26972add0fda6"></script>

The demonstration API key, dcb31709b452b1cf9dc26972add0fda6, is provided for use during development. If you plan to use the API in production, you should contact us by e-mailing info@desmos.com to obtain your own API key.

Collected Examples

• examples/geometry/multiple.html
• examples/geometry/saving-and-loading.html
• examples/geometry/default-state.html
• examples/geometry/screenshot.html
• examples/geometry/custom-colors.html