Back

Web Sketchpad Interchange Format

Version 4.8.0

 

Web Sketchpad Interchange Format

Contents

Introduction

This document describes the Web Sketchpad Interchange Format. This format is based on JSON, the JavaScript Object Notation. The interchange format delineates the characteristics of the objects that comprise a "web sketch", or geometric construction, that can be displayed and made interactive by Web Sketchpad. Refer to this format when interacting with web sketches using the sQuery API, or when programmatically creating web sketches and running them with WSPRunner.

The document, as a whole is a JSON document and must conform to JSON syntax. The majority of the following concerns definitions of kinds, constraint, and genera that are to be combined together to form a GObject definition. Each kind, constraint, or genus description in the reference material may have the following fields:

Description
A brief description of the kind, constraint or genus.
Inheritance
This class of object may inherit, in the object oriented programming sense, from another class of the same type. It will inherit the properties of its ancestor classes.
Usage
This field applies to constraints only. Constraints may only be meaningfully applied to certain Kinds. This field describes this relationship.
Existence Rule
This field applies to constraints only. It is the responsibility of the constraint to determine if a GObject "exists", that the object is possible to represent on the Euclidean plane. The existence of an object may change from moment to moment. This field describes the rule that is applied to determine existence.
Constrainers
This field applies to kinds only. It is a list of the constraints that can produce the given kind.
Reference Specification
In lieu of a formal product requirements specification, we need a means of assessing the correctness and completion of object classes. In many cases we are assessing this by comparison to existing software. This field describes where to look to find the archetype for the object class. In many cases this is the current desktop version of The Geometer's Sketchpad. While, most of this document describes the software as it is, this section is aspirational. Most objects do not yet meet the requirements as indicated.
JSON Fragment
This section describes the properties expected for the object. In the property descriptions curly brackets, "{}" indicate the expected data type, and parentheses surround default values.
Example
Where available, this field links to a working test page with examples of the object class. On these pages can be seen the JSON document that generates the web sketch.

This document is intended to describe the software as it is. There are inconsistencies and redundancies. These will be addressed as the project progresses.

Top-Level Structure

The Web Sketchpad Interchange Format is JSON based, and takes the form of a hash with three main parts: metadata, preferences, and pages.
  • "metadata" : {Document Metadata} Properties of the document as a whole that are not intended to be consumed by the Web Sketchpad engine, but may be of use to software in the context in which the document is placed.
  • "preferences" : {Document Preferences} (optional) General properties governing the document as a whole, and default values for sketch page preferences.
  • "resources" : {Document Resources} (optional) Resources used by one or more pages in the sketch, e.g. pictures.
  • "pages" : {Array} An Array of Pages that comprise the initial state of the web sketch.
  • "tools" : {Array} (optional) An Array of Tools included in the document.

Document Metadata

Information about the web sketch not relevant to the display of the web sketch, but which may be of interest to the web sketch context.
  • "copyright": {String} ("") Copyright information.
  • "description": {String |Array} ("") A description of Document. Can be represented as an single string or an array of strings.
  • "wsp-version": {String} Optional wsp version string. May be used to determine compatibility.
  • "wsp-build-number": {String} Optional wsp build number.
  • "wsp-build-stamp": {String} Optional wsp build stamp.
  • "exporter-version": {String} Optional version string for the exporter that created this document.
  • "exporter-build": {String} Optional build string for the exporter that created this document.
  • "height": {Number} Required. The height of the drawing in pixel units.
  • "name": {String} ("") The name of the document.
  • "original-document-name": {String} ("") Optional. The name of the document, for example, a GSP document, from which this document was created, if any.
  • "width": {Number} Required. The width of the drawing in pixel units.
  • "start-page": {String} Optional. Page id of initial page (generally, the one you would display on load).

Document Preferences

Default values for Page Preferences, and preferences specifying the availability of the page controller, widgets, tools, utility commands, and similar features.
  • "pageControl": {String} (default: "true") Optional. Whether the page cntroller appears, allowing the user to change pages.
  • "<name>tool": {String} (default: "all") Optional. One or more comma-separated lists of page numbers on which the specific named tool is available; "all" or "none" are acceptable.
  • "<name>widget": {String} (default: "all") Optional. One or more comma-separated lists of page numbers on which the specific named widget is available; "all" or "none" are acceptable.
  • "<name>util": {String} (default: "all") Optional. One or more comma-separated lists of page numbers on which the specific named utility-menu command is available; "all" or "none" are acceptable.

Document Resources

Resources available for use by the pages of the document.
  • "pictures": {Array} Optional. A list of images used in this web sketch.
  • "fontList": {Array} Required. A list of font families used in this document. Fonts are specified in labels, text, and buttons by specifying the zero-based index into this array.

Page

Each page of the document takes the form of a hash with three main parts: metadata, preferences, and objects.
  • "metadata" : {Page Metadata} Properties of the web sketch as a whole that are not intended to be consumed by the Web Sketchpad engine, but may be of use to software in the context in which the web sketch is placed.
  • "preferences" : {Page Preferences} General properties governing the web sketch as a whole.
  • "objects" : {Object} An Map of GObjects indexed by id that comprise the initial state of the web sketch.

Page Metadata

Information about the web sketch not relevant to the display of the web sketch, but which may be of interest to the web sketch context.
  • "id": {String} (1-based page index) The unique id of the page, corresponding to its order in the document.
  • "title": {String} ("Page title exported from GSP; otherwise defaults to the id.") Optional. The title of the page.

Page Preferences

Global properties of the web sketch that affect the display of the web sketch.
  • "fadeTraces": {Boolean} (false) Optional. Should we fade traces?
  • "fadeHalfLife": {Number} (5) Optional. Trace fading exponential decay half life in seconds.
  • "fadeSaturationFloor": {Number} (0.0652) Optional. Minimum alpha value that will clear the last vestiges of color.
  • "snapToGrid": {Boolean} (false) Optional. If true, independent points will snap to nearby locations when you drag them.
  • "precision": controls for the number of digits after the decimal point in the display of numbers.
    • "length": {Number} (2) Default precision for the display of numbers with length units.
    • "angle": {Number} (2) Default precision for the display of numbers with angle units.
    • "scalar": {Number} (2) Default precision for the display of numbers with no units.
  • "units": controls the unit type for a given unit family.
    • "length": {LengthUnit} ("cm") The length unit type for this document.
    • "angle": {AngleUnit} ("deg") The angle unit type for this document.
  • "colorableComponent": controls the default color of components of the sketch.
    • "Points":
      • "color": {Color} ("red") Default "main" color applicable to this component.
    • "Straights":
      • "color": {Color} ("navy") Default "main" color applicable to this component.
    • "Curves":
      • "color": {Color} ("green") Default "main" color applicable to this component.
    • "Interior":
      • "color": {Color} ("rgb(138,102,217)") Default "main" color applicable to this component.
    • "Plot":
      • "color": {Color} ("purple") Default "main" color applicable to this component.
    • "PointLocus":
      • "color": {Color} ("maroon") Default "main" color applicable to this component.
    • "Selection":
      • "color": {Color} ("rgb(195,0,195)") Default "main" color applicable to this component.
    • "Background":
      • "color": {Color} ("white") Determines the fill-color of the blank sketch canvas "behind" any composited objects. Also used in establishing other colors that harmonize with the primary background color.
      • "composite-mode": {String} ("source-over", unless "color" is "white", then "destination") Determines the compositing operation used in applying the fill-color of the blank sketch canvas. "source-over" paints with the color, "destination" leaves the background intact. The default values of "color" and "composite-mode" result in "white" being used for harmonizing colors, but leaving intact the background behind the sketch canvas.
    • "CoordSys":
      • "color": {Color} ("silver") Default "main" color applicable to this component.
    • "TextGObject_BackgroundContrast":
      • "color": {Color} ("black") Default "main" color applicable to this component.
    • "ActionButton":
      • "color": {Color} ("rgb(255,128,0)") Default "main" color applicable to this component.
    • "LabelText_BackgroundContrast":
      • "color": {Color} ("black") Default "main" color applicable to this component.
    • "Axis":
      • "color": {Color} ("rgb(96,96,96)") Default "main" color applicable to this component.
    • "AngleMarker":
      • "color": {Color} ("rgb(64,64,64)") Default "main" color applicable to this component.
    • "Picture":
      • "color": {Color} ("red") Default "main" color applicable to this component.
  • "text": controls the appearance of text.
    • "mathItalicization": {Boolean} (true) Optional. Italicize all mathematical labels? If true use automatic italics for most object labels, including geometric objects, measurements, parameters, and user-defined function names. Calculations and function definitions appear using mathematical italics in a way that is consistent with the most common standards for mathematical typesetting.
    • "textTypes": controls the appearance of text.
      • "Label": {TextStyle} ({"font-family": "Times", "font-size": 24, "font-weight": "bold"}) Default style attributes for text of this class.
      • "Caption": {TextStyle} ({"font-family": "Times", "font-size": 16}) Default style attributes for text of this class.
      • "Measurement": {TextStyle} ({"font-family": "Times", "font-size": 18) Default style attributes for text of this class.
      • "Action": {TextStyle} ({"font-family": "Arial", "font-size": 16}) Default style attributes for text of this class.
      • "Table": {TextStyle} ({"font-family": "Arial", "font-size": 14}) Default style attributes for text of this class.

GObjects

GObjects are the fundamental geometric entities which make up Sketchpad documents. The GObjects form a directed tree in parent / child relationship. Every GObject is characterized by its
  • Kind, which defines its fundamental layout.
  • Constraint, which defines its geometric relationship to its parent GObjects.
  • Genus, which defines its role as a geometric object.
The (Kind,Constraint,Genus) triple defines a GObject type. Note, though, that not all combinations of (Kind,Constrain,Genus) are valid - far from it.

Tool

A tool is used for creating new objects in a sketch. It is comprised of a set of objects that get instantiated into the sketch on each tool invocation.
  • "metadata" : {Tool Metadata} Properties of the tool that describe it, for purposes of display or UI.
  • "objects" : {Array} An Array of GObjects that comprise the tool production. Givens have ids of the form "given" followed by an integer 0-n that signifies the order in which a given should be matched. A tool with 2 givens will have givens labeled "given0" and "given1"

Tool Metadata

  • "name" : {String} Required. The name of the tool
  • "image" : {Number} Optional. Index into resources of the image associated with this tool.

Object Kinds

The set of Kinds form a single inheritance hierarchy rooted at kind.

Object Constraint

The set of Constraints form a single inheritance hierarchy rooted at Constraint.

Object Genus

The set of Genera form a single inheritance hierarchy rooted at Genus.

Types

AffineTransform
An affine transformation of the plane.
m00m10m20
m01m11m21
001
*
x
y
1
=
x'
y'
1
This is a standard matrix form with 6 free parameters.
  • "m00": {Number} Frequently called a
  • "m11": {Number} Frequently called b
  • "m11": {Number} Frequently called c
  • "m12": {Number} Frequently called d
  • "m20": {Number} Frequently called dx
  • "m21": {Number} Frequently called dy
AngleUnit
The unit of measure for angle. ("rad", "deg")
Array
JSON array
Boolean
JSON boolean
Color
CSS Color String or 'random' for system generated color.
FontFamily
An index into the font table provided in the preferences section of this interchange document.
FontSize
CSS font-size String
FontStyle
CSS font-style String
FontWeight
CSS font-weight String
GeometricPoint
An x,y coordinate in the browser element coordinate system.
  • "x": {Number}
  • "y": {Number}
GObject
A geometric object in the current web sketch.
Image
An html image or an index. If image it will have this format:
  • "src": {String} The url for the image
  • "width": {Number} The width of the image in pixels
  • "height": {Number} The height of the image in pixels
LengthUnit
The unit of measure for length. {"px", "in", "cm"}
LetterSpacing
CSS letter-spacing String
LineStyle
How paths are drawn. {"solid", "dotted", "dashed"}
MeasureType
The family of units for this measure.
Name
A JSON string beginning with an alphanumeric character and consisting only of alphanumeric characters and underbars.
NameOrigin
How to label a measurement or other textual representation of a value. From Desktop sketchpad. {"NamedFromTemplate", "NoVisibleName", "NamedFromCustom", "NamedFromLabel"}
Number
JSON number
Object
JSON object { }
StopCondition
a positive JSON number (duration in seconds), "lastActionStops", or "firstActionStops"
String
JSON string
TextAlignment
CSS text-align String
TextDecoration
CSS text-decoration String
TextOverbar
The overbar style. { "none", "segment", "ray", "line", "arc", "hat" }
TextStyle
A set of properties which govern the appearance of text.
  • "font-family": {FontFamily}
  • "font-size": {FontSize}
  • "font-weight": {FontWeight} ("normal")
  • "font-style": {FontStyle} ("normal")
  • "text-decoration": {TextDecoration} ("normal")
  • "letter-spacing": {LetterSpacing} ("normal")
  • "color": {Color} ("rgb(0,0,0)")
UnivExpressionType
Sketchpad expression types. Map to Desktop enum: UnivExpressionTypes. {"YofX_FunctionExprType", "XofY_FunctionExprType", "RofT_FunctionExprType", "TofR_FunctionExprType", "UniMeasure_ExprType"}
VerticalAlignment
CSS vertical-align String
TickMarkStyle
Tick mark style. {"Crossbar", "OpenArrow", "HollowArrow", "SolidArrow"}
ArrowDirection
Arrow direction. {"Forward", "Backward"}