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.10/calculator.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 instance.

Constructor

constructor Geometry(element, [options])

Creates a Geometry object to control the embedded instance 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.

options is an optional object that specifies features that should be included or excluded. Any option available to a Desmos.GraphingCalculator instance, documented here, may also be passed to a Desmos.Geometry instance.

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 tool. Used in conjunction with Geometry.setState to save and restore 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 instance
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 construction 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 construction
var fullsize = geometry.screenshot();

// Capture a double resolution screenshot of the construction 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.

There is also an asynchronous version of the screenshot method, documented here.

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

Additionally, primitive object types are assigned a default color:

Object Color Hex String
point purple #6042a6
line/ray/vector/polygon blue #2d70b3
circle/arc/compass green #388c46
angle black #000000

You may optionally provide a custom color palette for an instance by passing in a colors constructor option, which should be an object whose values are valid hex colors. See the related graphing calculator documentation for more information.

Example:

var customColors = {
  pink: '#e91e63',
  indigo: '#3f51b5',
  purple: '#e040fb',
  cyan: '#00bcd4'
};
var elt = document.getElementById('geometry');
var geometry = Desmos.Geometry(elt, { colors: customColors });

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

Customizing the Toolbar

As in the graphing calculator, setting the authorFeatures option to true adds some UI intended for content authors who want to be able to set expression- or state-level properties that they do not want to be modified by end users when that same state is loaded with authorFeatures set to its default value of false. For example, authorFeatures allows you to create secret folders and readonly expressions, as well as disable mouse/keyboard/touch interactions on the graph paper for a plotted expression or object.

In a geometry instance, the authorFeatures flag also adds some UI to the settings menu for customizing the toolbar. Authors may choose to enable or disable individual tools, either conditionally or unconditionally, and those customizations will be applied when the construction is opened with { authorFeatures: false }.

Note that toolbar customizations are features of the construction, and not of the geometry instance itself. This means that they are serialized in the results of Geometry.getState and will be applied as the result of a call to Geometry.setState. If you want toolbar customizations to survive a user resetting the construction, consider setting a default state.

See the custom toolbar example.

More Documentation

The geometry tool is built on top of the graphing calculator and shares its underlying API. For more information about this shared API surface, see the graphing calculator API documentation here.

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