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.7/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.

name default description
'construct.perpendicular' true Enable the perpendicular line construction tool
'construct.parallel' true Enable the parallel line construction tool
'construct.midpoint' true Enable the midpoint construction tool
'construct.compass' true Enable the compass tool
'transform.reflection' true Enable the reflection tool
'transform.translation' true Enable the translation tool
'transform.rotation' true Enable the rotation tool
'transform.dilation' true Enable the dilation tool
'transform.scaled-rotation' true Enable the rotation/dilation tool
transformations true Display the "Transform" pane
sidebarCollapsed false Begin with the sidebar collapsed
border true Add a subtle 1px gray border around the entire board
headerbar true Display the undo/redo and settings menu icons
settingsmenu true Display the settings menu icon
undoredo true Display the undo/redo icons
sidebar true Display the construction toolbar and pane
autosize true Automatically resize the instance when its parent container resizes
selection true Allow objects to be selected with the mouse and keyboard
labels true Enable the creation and editing of object labels.
transparentBackground false Give the board a transparent background instead of a white one.
colorMap see below Define a custom color palette. See Colors below.

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])

Reset to a state previously saved using Geometry.getState. options is an optional object that controls the behavior of when setting the state.

Name Type Default Description
allowUndo Boolean false Preserve the undo/redo history.

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:

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:

Color Hex String
red #c74440
blue #2d70b3
green #388c46
purple #6042a6
orange #fa7e19
black #000000
gray #aaaaaa

Additionally, primitive object types are assigned a default color:

Object Color Hex String
point red #c74440
line/ray/vector blue #2d70b3
circle green #388c46

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.7/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