When a new filter is created or when an existing filter's menu item is clicked, a dialog box will appear that allows the filter to be configured. Both the filter as a whole and individual paths and locations provide a mode that determines how entries are filtered. The choices for a mode are the following:

• Default. No changes are made for a path or location
• Selectable. A path or location is marked as selectable. When drawn, both paths and control points are drawn.
• Drawable. Paths are drawn but control points are not drawn.
• Invisible. The path or location is not drawn.

• Apply. The filter will be applied.
• Save Only. The filter will be saved but not applied.
• Delete. The filter will be deleted, thus removing it from the Filter menu.

When a filter is applied, the mode for the filter as whole will first be applied to each path and location. Then the modes for individual paths are applied. Typically, most of the modes for individual paths and locations will be set to Default, so that the filter's overall mode will be used, and a few will be set to different values. The modes are initially set to Default for individual paths and locations. A filter's overall mode is initially set to Invisible.

When a filter has been applied, the menu title will change from Filters to *Filters*. Clearing the filters will restore the title to Filters and make all paths and locations selectable.

The Help menu

• Manual. This option shows the manual in a window that contains two panes: one with a table of contents and the other with the manual itself.
• Print Manual. This option opens a printer dialog box and allows the user to produce a printed copy of the manual.
• Browser. This option opens the system's default browser and displays the manual in it. As a side effect, an embedded web server will also be started, and that web server can be accessed by other users. If the port number is not set or is set to zero, the system will choose the port to use. For Firefox, if NoScript is used, scripting must be enabled: otherwise the table of contents will not be shown due to the use of XSL.
• Port for Manual`s Webserver. When a TCP port was not specified on the command line, this option gives the user a chance to change the port number until the web server is started.
• Start Manual's Webserver. This option starts the web server used to show the on-line manual. While EPTS can display the manual directly, a web server is useful when a nearby computer can be used to display the manual and EPTS is not installed on that computer. If the port number is set to 8080 the corresponding URL will be <http://HOSTNAME.local:8080/>, where HOSTNAME is the name of the computer on which EPTS is installed. As a use case, suppose two people are in a coffee shop and are using EPTS, which is installed on one computer. Starting the EPTS web server will allow the manual to be displayed on the other computer while the one on which EPTS is installed will be used to run the EPTS application.

Using the mouse

• ALT key and primary mouse button pressed. The image can be dragged, and scrollbars will move in the opposite direction to that in which the cursor moves. The image, however, cannot be dragged beyond the range that the scrollbars support. If a window system has a short cut that uses the same key-mouse combination, the window system's behavior may occur instead. In this case, use the drag-image mode Edit menu option to put EPTS into the desired state.
• Control Key and primary mouse button pressed. This combination is used while creating a path or extending a path. The mouse must be positioned over a point when the left button is pressed. The point can then be dragged to a new location. The selected point will have a circle around it. If a window system has a short cut that uses the same key-mouse combination, the window system's behavior may occur instead.
• No keys but the primary mouse button clicked. When a cross-hair cursor is shown, a point will be added, either an isolated point or an additional point along a curve. When the normal 'arrow' cursor is shown, this option allows one to select or deselect a point. A point is selected when the mouse is clicked while positioned over it. A point is deselected by clicking on an area of the image that does not contain a point. When a point is selected, a ring is drawn around it.
• A popup menu is requested. The key sequence is system dependent. On X-windows systems, one typically presses the button on the opposite side of the mouse from the primary button. In the Java look and feel, clicking the this mouse button will make the popup menu stay up. Popup menus are context sensitive. They can appear when a point has been selected or when a cross-hair cursor is shown and there is a previous point to modified.

Popup menus

When a path is not being created or extended, but a point on a path has been selected, a popup menu is also available. This menu provides the following options:

• Delete Point. This option deletes the selected point from the path.
• Change Point Type. This option allows one to change the type of the selected point. The choice types is dependent on the types of the surrounding points. If the path is closed and all the intermediate points are spline points, the type of a selected point cannot be changed. One can, however, break the loop and extend the path so that the last point is a SEG_ENDpoint whose location is the same as the initial point on the path.
• Insert Before Point. This option allows one to insert a new point into a path before the selected point. One may click the mouse after moving it to the desired point, or one may use one of the menu items in the Tools menu that will get or set a point (these have the shortcuts G, P, and M).
• Insert After Point. This option allows one to insert a new point into a path after the selected point. One may click the mouse after moving it to the desired point, or one may use one of the menu items in the Tools menu that will get or set a point (these have the shortcuts G, P, and M).
• Break Loop. This option turns a closed path into an open path. To close it again, first extend the path.
• Append To Path. This option allows one to add new points to a path. It will also re-order the table (for reasons of convenience, when a path is extended, it is moved to the end of the table). Existing specified points along the path (spline knots, segment end points, and intermediate control points) will be displayed using blue circles to distinguish these from newly added points. This provides the same behavior as the Edit menu option Append to a Bezier Path.
• Extend Path. This option allows one to add new points to a path. It will also re-order the table (for reasons of convenience, when a path is extended, it is moved to the end of the table). This provides the same behavior as the Edit menu option Extend a Bezier Path.

Keyboard shortcuts

• Control-Q. This will cause EPTS to terminate.
• Control-S. This will save the current state or configuration displayed in window or dialog box. If the current session was restored from a saved state or configuration, the corresponding file will be replaced.

• Control-Minus. Zoom out.
• Control-Plus. Zoom in. The Zoom menu will list this as Ctrl-Equals.
• Control-0. Restore the zoom factor to the original size (1 to 1).
• Control-Right-Arrow. Move the horizontal scroll bar to the right.
• Control-Left-Arrow. Move the horizontal scroll bar to the left.
• Control-Up-Arrow. Move the vertical scroll bar up.
• Control-Down-Arrow. Move the vertical scroll bar down.
• Alt-A. Append points to a Bézier path (at least one path must exist). Existing specified points along the path (spline knots, segment end points, and intermediate control points) will be displayed using blue circles to distinguish these from newly added points. The Undo Point Insertion or Move menu item, whose shortcut is Control-Z, can be used to delete newly added points, but not the existing ones shown in blue, nor the path's initial point. Points can be added to the path, and the path can be terminated, using the same operations used when a path is newly created. For a closed path, the loop must be broken for this shortcut to be used.
• Alt-E. Extend a Bezier path (at least one path must exist). Points can be added to the path, and the path can be terminated, using the same operations used when a path is newly created. For a closed path, the loop must be broken for this menu option to be used. The Undo Point Insertion or Move menu item, whose shortcut is Control-Z, can be used to delete points from the chosen path, starting at the end of the path.
• Alt-B. Add a Bézier path. The user will be asked to supply a variable name that has not been used before. If that variable name is not provided or consists of just whitespace, a name will be generated. A generated name starts with the string path and ends with a positive integer. The text field in the dialog box accepts parameters separated from the variable name and each other by semicolons. Each parameter consists of a key and a value, separated by an "=" symbol. Leading and trailing whitespace is ignored for both keys and values. The keys are any of the following:
  • key. The value is an identifier used to classify paths in some way. A key should have the same syntax as a Java identifier, and printable ASCII is preferred.
  • link. While the value will typically be a URL or URI, any text is allowed. A link is assumed to be a reference to some associated object.
  • descr. The value is an arbitrary (but typically short) string containing text describing the path, except that the string may not contain a semicolon. The string should not be quoted as quotes will be part of the value.
  EPTS treats these parameters as purely annotative, but they will be accessible in templates. The use in these cases is template specific. All are optional unless required by a template.
• Alt-D. This toggles whether drag-image mode is in effect, and can be used when a window system provides shortcuts that use the ALT key with the primary mouse button.
• Alt-G. Measure the graph-coordinate-space distance between two points. To provide a meaningful distance, graph coordinate space must be configured first. The Configure CGS menu item allows graph coordinate space to be configured.
• Alt-I. Measure the image-space distance between two points.
• Alt-P. Add an isolated point. The user will be asked to supply a variable name that has not been used before. If that variable name is not provided or consists of just whitespace, a name will be generated. A generated name starts with the string pt and ends with a positive integer. The text field in the dialog box accepts parameters separated from the variable name and each other by semicolons. Each parameter consists of a key and a value, separated by an "=" symbol. Leading and trailing whitespace is ignored for both keys and values. The keys are any of the following:
  • key. The value is an identifier used to classify points in some way. A key should have the same syntax as a Java identifier, and printable ASCII is preferred.
  • link. While the value will typically be a URL or URI, any text is allowed. A link is assumed to be a reference to some associated object.
  • descr. The value is an arbitrary (but typically short) string containing text describing the point but may not contain a semicolon. The string should not be quoted as quotes will be part of the value.
  EPTS treats these parameters as purely annotative, but they will be accessible in templates. The use in these cases is template specific. All are optional unless required by a template.
• Control-P. This will print the table.
• Ctrl-T. Display the table in a separate window.

By contrast, some key combinations apply only when a path or location exists:

• Ctrl+Alt-M. Move an existing point or path.
• Ctrl+Alt-N. Create a new path by applying an affine transformation that scales an existing path along its principal axes, rotates the path about its center of mass, and applies a translation. The translation's values determines the offsets of the center of mass from its starting location to its new location. A dialog box sets up the affine transformation.
• Ctrl+Alt-R. Rotate an existing path.
• Ctrl+Alt-S. Scale an existing path as described in the menu-item documentation (which includes a description of the use of modifier keys).
• Ctrl+Alt-T. Modify an existing path by applying an affine transformation that scales the existing path along its principal axes, rotates the path, and apply a translation to the path. The translation's values determines the offsets of the center of mass from its starting location to its new location. A dialog box sets up the affine transformation.
• Alt-X. Delete a location or Bézier path.

• Right-Arrow. When this key is clicked, a cross-hair cursor will move to the right.
• Left-Arrow. When this key is clicked, a cross-hair cursor will move to the left.
• Up-Arrow. When this key is clicked, a cross-hair cursor will move to up.
• Down-Arrow. When this key is clicked, a cross-hair cursor will move to down.
• A. When the A key is pressed (without a modifier key, regardless of whether the caps-lock key is in use), if a curve is being created and the current point is the end of a segment, a dialog box creating a circular arc will appear. This is equivalent to selecting the Add Arc menu item from the Tools menu.
• C. When the C key is pressed (without a modifier key, regardless of whether the caps-lock key is in use), the next point will be a control point. If a control point is not allowed, the keystroke will be ignored.
• E. When the E key is pressed (without a modifier key, regardless of whether the caps-lock key is in use), the next point will be an end-of-segment point.
• L. When the L key is pressed (without a modifier key, regardless of whether the caps-lock key is in use), the current path will be ended in a loop. This option will be ignored if the last point is a control point or if the last point is a spline point and there is an end-of-segment point that is already part of the path.
• P. When the P key is pressed (without a modifier key, regardless of whether the caps-lock key is in use), a dialog box will appear that allows one to enter GCS coordinates for a point. The behavior is identical to clicking the left mouse button when the cross-hair cursor appears over the corresponding point. This key is ignored when not creating a location or a point on a Bézier curve.
• S. When the S key is pressed (without a modifier key, regardless of whether the caps-lock key is in use), the next point will be a spline point. If a spline point is not allowed, the keystroke will be ignored.
• V. When the V key is pressed (without a modifier key, regardless of whether the caps-lock key is in use), if a curve is being created and the current point is not a control point or spline point, a dialog box specifying a vector to the end of the next segment will appear. This is equivalent to selecting the Add Vector menu item from the Tools menu.
• Z. When the Z key is pressed (without a modifier key, regardless of whether the caps-lock key is in use), the current path will remain open and will be ended. The type of the last point will be changed to an end-of-segment point.
• Control-Z. This is an "undo" operation. It undoes the last entry to a path when a path is being created or extended, but will not modify preexisting points belonging to the current path when the Append to a Bezier Path edit-menu item is used.

Templates

To use a template, one must also specify an output file, which may be done with the -o command-line option. EPTS will not provide a GUI when templates are used with the -o command-line option. If the argument to the -o option is "-", the output will be sent to standard output. If the -o is not provided and the argument file is an eptt file, a GUI will be started to allow the eptt file to be edited. If the -o is provided with an eptt file, the template options will be recovered from the eptt file and the file specified as the argument to the -o option will be used as the output file. For this case, the eptt file must be in the current working directory. In practice, this is typically the case due to the use of tools such as make. For example, a makefile may contain the rule

image.svg: image.epts image.eptt
        epts -o image.svg image.eptt

Built-in templates

      epts -o paths.js --template:ECMAScriptPaths saved.epts

      epts -o paths.js --template resource:ECMAScriptPaths saved.epts

      epts -o path.js --template:ECMAScriptPaths \
          --tname firstPath -tname secondPath saved.epts

The built-in table templates are the following:

• resource:distances. This will print the distances and corresponding path parameters for those points along a path that are spline points or points on segment boundaries. The path parameters are integer-valued, and for the path parameter 0.0, the corresponding distance is always zero. For paths that have subpaths, the distances and path parameters are those appropriate for each subpath.
• resource:ECMAScript. This will print the information included in the EPTS table. Each path or location is represented by an ESP or ECMAScript variable. For locations, the value assigned to the variable is an object whose properties x and y provide the coordinates of the point. If there are no --tname options, all paths and locations are included in the output; otherwise only the ones specified by --tname options are included. For paths, if stroke or color options are not used, the object will be an array of objects, each describing a control point. In this case, the value assigned to the variable will be an object that can be used to configure an instance of org.bzdev.geom.SplinePathBuilder. When the corresponding --tname option's argument names a single EPTS path, the array can also be used to configure an instance of org.bzdev.anim2d.AnimationPath2DFactory or org.bzdev.geom.BasicSplinePathBuilder. If a stroke or color option is provided, the object will be an array of two objects, where the first object describes a stroke, color, and Z-order, and where the second object contains an array of control points describing the path itself. Because of the constraints imposed by the class AnimationPath2DFactory the corresponding --tname option must name a single EPTS path when a stroke or color option is provided.
• resource:ECMAScriptLayers. This option will print the information included in the EPTS table. Each path is represented by an ESP or ECMAScript variable. Location entries are ignored. For the paths specified by --tname options, or all paths if there are no --tname options, the value assigned to each variable will be an array of objects. The array can be used to configure an instance of org.bzdev.anim2d.AnimationLayer2DFactory. One may use the --tname option to include only specific paths and optionally to use a new variable name that represents a single path or the concatenation of multiple paths. When a --tname option is used, a --winding-rule option may be used, as can color or stroke options.
• resource:EMCAScriptLocations. This template provides the same ESP or ECMAScript statements that the resource:ECMAScript template produces, but only locations are included, not paths. For the locations specified by the --tname options, or all locations if there are no --tname options, the value assigned to each variable will be an object specifying a location.
• resource:ECMAScriptPaths. This template provides the same ESP or ECMAScript statements that the resource:ECMAScript template produces, but only paths are included, not locations. For the paths specified by --tname options, or all paths if there are no --tname options, the value assigned to each variable will be an array of objects. The array can be used to configure a path using org.bzdev.anim2d.AnimationPath2DFactory or org.bzdev.geom.BasicSplinePathBuilder.
• resource:JavaLocations. This template provides a Java class containing fields that are instances of the Java class java.awt.geom.Path2D with each field named by the name provided in a --tname option. If there are no --tname options, the field names are the names of all the locations defined in the EPTS table. Multiple --tname options are allowed.
• resource:JavaPathBuilders. This template provides a Java class containing fields that are instances of the Java class org.bzdev.geom.SplinePathBuilder with each field named by the primary name (the name before a colon in the argument for this --tname option) in a --tname option for a path. If there are no --tname options, the field names are the names of all the paths defined in the EPTS table. A --winding-rule option preceding a --tname option will configure a winding rule for the corresponding spline-path builder, but any stroke or color options will be ignored.
• resource:JavaPathFactories. This template provides a Java class containing fields that are instances of the Java interface org.bzdev.obnaming.NamedObjectFactory.IndexedSetter with each field named by the name provided by a a --tname option for a path. If there are no --tname options, the field names are the names of all the paths defined in the EPTS table. The arguments to the --tname options must be simple names that match the names of paths defined in the EPTS table. For a specific --tname option, color or stroke options can be specified (these must precede the --tname option to which they apply).
• resource:YAMLLayers. This template creates a YAML file with an "execute" property that provides a series of ESP variable definitions corresponding to the variable definitions created with the resource:ECMAScriptLayers template.
• resource:YAMLLocations. This template creates a YAML file with an "execute" property that provides a series of ESP variable definitions corresponding to the variable definitions created with the resource:ECMAScriptLocations template.
• resource:YAMLPaths. This template creates a YAML file with an "execute" property that provides a series of ESP variable definitions corresponding to the variable definitions created with the resource:ECMAScriptPath template.
• resource:YAML. This template creates a YAML file with an "execute" property that provides a series of ESP variable definitions corresponding to the variable definitions created with the resource:ECMAScript template.
• resource:HTMLImageMap. This template creates an HTML MAP element. Such elements must have a name to be useful. The command-line option --mapName can be used to provide this name, or the GUI can be used, in which case the entry will appear in the Global Parameters tab. The image map will consist of a sequence of AREA elements, each indicated by an EPTS path with some variable name. An AREA's SHAPE attribute will have the values circle, rect, or poly, which will also be the value of a variable name's key parameter. When the key's value is circle, rect, or poly, a template-processor directive with the same name will also exist (i.e., if the value of key is circle, then a directive named circle with the value circle will exist as well). An AREA's HREF attribute's value is the value of the variable name's link parameter, and an AREA's ALT attribute's value is the value of the variable name's descr parameter. How the path is drawn depends on the SHAPE attribute. For
  • circle, the path is a single line segment that starts at the center and ends at the circle.
  • rect, the path starts at the upper left corner of the rectangle and ends at the lower right corner.
  • poly, the path should be closed path of straight line segments providing a polygon.

    - create
        - var: path1
          name: path1
          factory: pathf
          configuration: = pdata

The built-in path-iterator templates are

• resource:area. This template requires the use of a --pname option to specify a path name, or to create a new path that is the concatenation of several existing paths. It provides the area enclosed by the path; "NaN" if the path contains any open segments. If the command was run with the --gcs option, the units are graph-coordinate-space units; otherwise they are user-space units.
• resource:areaVars. This template requires the use of a --pname option to specify a path name, or to create a new path that is the concatenation of several existing paths. It provides the area enclosed by the path; "NaN" if the path contains any open segments. If the command was run with the --gcs option, the units are graph-coordinate-space units; otherwise they are user-space units. The output will be formatted as one or more 'var' statements, with "_area" appended to the name provided at the start of each --pname option. The variables will be suitable for use by the scripting languages ECMAScript and ESP.
• resource:circumference. This template requires the use of a --pname option to specify a path name, or to create a new path that is the concatenation of several existing paths. It provides the circumference the path; "NaN" if the path contains any open segments. If the command was run with the --gcs option, the units are graph-coordinate-space units; otherwise they are user-space units.
• resource:circumferenceVars. This template requires the use of a --pname option to specify a path name, or to create a new path that is the concatenation of several existing paths. It provides the circumference the path; "NaN" if the path contains any open segments. If the command was run with the --gcs option, the units are graph-coordinate-space units; otherwise they are user-space units. The output will be formatted as one or more 'var' statements, with "_circumference" appended to the name provided at the start of each --pname option. The variables will be suitable for use by the scripting languages ECMAScript and ESP.
• resource:pathlength. This template requires the use of a --pname option to specify a path name, or to create a new path that is the concatenation of several existing paths. It provides the length of the path (the sum of the lengths of all its segments). If the command was run with the --gcs option, the units are graph-coordinate-space units; otherwise they are user-space units.
• resource:pathlengthVars. This template requires the use of a --pname option to specify a path name, or to create a new path that is the concatenation of several existing paths. It provides the length of the path (the sum of the lengths of all its segments). If the command was run with the --gcs option, the units are graph-coordinate-space units; otherwise they are user-space units. The output will be formatted as one or more 'var' statements, with "_length" appended to the name provided at the start of each --pname option. The variables will be suitable for use by the scripting languages ECMAScript and ESP.
• resource:SegmentsCSV. This template requires the use of a --pname option to specify a path name, or to create a new path that is the concatenation of several existing paths. The template will create its output in CSV (Comma Separated Values) format, describing the specified path. The name of the path will not appear in the output. The CSV values contain 7 columns, some of which may be empty. The first is type, whose value can be SEG_CLOSE, SEG_CUBICTO, SEG_LINETO, SEG_MOVETO, or SEG_QUADTO, matching names defined by the class java.awt.geom.PathIterator. The remaining values are x0, y0, x1, y1, x2, and y2. The values for these are numbers or empty strings.

Template syntax

Templates specify an output format for points and paths using the syntax specified by the Java class org.bzdev.util.TemplateProcessor. Instances of this class are constructed using a tree consisting of objects whose type is org.bzdev.util.TemplateProcessor.KeyMap or is org.bzdev.util.TemplateProcessor.KeyMapList. This tree determines the directives a give template processor supports and how those directives are used. Each value corresponding to a key is either a string (java.lang.String), a KeyMap, an array of KeyMap, or a KeyMapList. The keys name directives. When a key's value is a string, the directive is a simple directive. Otherwise it is an iterative directive. When the value of an iterative directive is a single KeyMap, the iteration occurs once and this can be used a conditional (provided when the directive is defined and missing when it is not defined).

A template contains a mixture of text and directives stored in a text file. In a template, directives start with the sequence "$(" and end with a closing ")". A simple directive contains a variable name and its value is a string that provides text that will be substituted for the directive. For example, the directive "$(varname)" will be replaced by a string containing a variable name. The directive "$$" is replaced with a single dollar sign. An iterative directive consists of a name, a colon (":") and a second name. Its value is either a key map (in which case it is treated like a list with a single value, or a list or array providing key maps over which one iterates). A following simple directive containing the second name will then end the iterative block.

Directives can be globally defined or can be scoped to apply only within an iterative block. When blocks are nested and a directive is defined at multiple levels, the most recent definition is used. In the following description, we will frequently refer to a directive by the name of its key.

Table templates

EPTS provides key maps appropriate for representing its table entries. for these tables, EPTS defines several global directives:

• class. This is a global directive that provides the simple name of a Java class. Unless documentation for a template states otherwise, this is the class name for a single class being defined.
• hasPackage. This is an empty iterative directive. When present, it will provide a single iteration and indicates that the key package has a non-null value.
• items. This is an iterative directive providing a sequence of items described below
• optSpace. This is a global directive that expands to either an empty string or a single space As typically used, it will appear after the directive public appears. This is primarily used in templates as part of the sequence "$(public)$(optSpace)", so that when public is not defined, no text will be added, and when public is defined, there will be space following the public directive.
• mapName is a global directive that is a synonym for class: Both always have the same value. mapName is provided because it is a more mnemonic directive name for HTML image maps.
• package. This is a global directive that provides the fully qualified class name of a Java package. Unless documentation for a template states otherwise, this is the name of a package in which the template will define a single class whose name is specified by a class directive.
• packageDir. This is global directive that has the same value as the package directive but with each '.' replaced with '/'. It is not used by build-in templates. One use is for templates that help create HTML image maps for Javadoc comments, where a package name has to be replaced with the corresponding directory path.
• public. This is a global directive that expands to either an empty string or to the string "public". As typically used, it will appear before the Java keyword class in code generated by a template.

The directive items, as mentioned above, is an iterative directive. This directive iterates through a list, setting values for the following directives:

• varname. This is a simple directive defining a variable name associated with a location or path.
• "key". This provides a key that can be used to classify paths and locations. The value for the key is also the name of another key, and both share the same value. E.g., if the value for "key" is "foo", there were be a key "foo" whose value is also "foo".
• "link". This value associates a path or location with some other object. For example, it could be a URL or URI.
• "descr". This value provides a short description of a path or location.
• index. An overall index. This value is incremented for each line in the table.
• vindex. An variable-name index. This value is incremented whenever a variable name changes.
• location. This is an iterative directive that defines a specific, isolated point. While iterative, each definition contains only a single point. Both location and pathStatement will not both be present at a specific iteration, although one of the two will be present.
• pathStatement. This is an iterative directive that defines the control points for a path. While iterative, each pathSegment definition contains a single key map as its value. Both location and pathStatement will not both be present at a specific iteration, although one of the two will be present.

      $(items:endItems)$(varname)
      $(endItems)

The value for location is a key map containing the following keys describing a point:

• x. The X coordinate of the point in graph coordinate space.
• y. The Y coordinate of the point in graph coordinate space.
• xp. The X coordinate of the point in image space.
• yp. The Y coordinate of the point in image space, measured from top to bottom(the standard Java convention).
• ixp. The X coordinate of the point in image space, rounded to the nearest integer.
• iyp. The Y coordinate of the point in image space, measured from top to bottom (the standard Java convention), rounded to the nearest integer.
• ypr. The Y coordinate of the point in image space measured from bottom to (the reverse of the standard Java convention, following the convention used in mathematics instead).

Similarly, the value for pathStatement is a key map containing the following directives:

• draw. This directive has the value "true" or "false". When true, a path's outline will be drawn. Otherwise, the path's outline will not be drawn.
• fill. This directive has the value "true" or "false". When true, a path will be filled. Otherwise, the path's outline will not be filled.
• hasAttributesThis is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), the directives draw and/or fill will have the value true, and attributes defining colors or strokes will exist.
• hasDashIncrement. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: dashIncrement, whose value is the length of a "-" or " " in a dash pattern. The units are GCS units when gcsMode is true and user-space units when gcsMode is false or not defined.
• hasDashPattern. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: dashPattern, whose value is a string consisting of "-" and " " characters, starting with a "-". A sequence of N "-" or N " " denotes a dash or gap whose length is N multiplied by the dash increment. The pattern created will be periodic.
• hasDashPhase. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: dashPhase, whose value is the offset at which the dash/gap pattern starts. The units are GCS units when gcsMode is true and user-space units when gcsMode is false or not defined.
• hasDrawColor. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: drawColor, whose value is a CSS color specification that indicates the color used when drawing paths.
• hasFillColor. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: fillColor, whose value is a CSS color specification that indicates the color used when filling paths.
• hasGcsMode. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: gcsMode, whose value is "true" if strokes are defined using GCS units, or "false" if strokes are defined using user space or image space units.
• hasMiterLimit. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: miterLimit>, whose value is the "limit to trim a line join that has a JOIN_MITER decoration. A line join is trimmed when the ratio of miter length to stroke width is greater than the miter-limit value. The miter length is the diagonal length of the miter, which is the distance between the inside corner and the outside corner of the intersection. The smaller the angle formed by two line segments, the longer the miter length and the sharper the angle of intersection. The default miter-limit value of 10.0f causes all angles less than 11 degrees to be trimmed. Trimming miters converts the decoration of the line join to bevel." (The quote is from the Java API documentation for the class java.awt.BasicStroke.) When present, the minimum allowed value for the miter limit is 1.0. The units are GCS units when gcsMode is true and user-space units when gcsMode is false or not defined.
• hasStrokeCap. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: strokeCap, whose value is either BUTT, ROUND, or SQUARE. The values defines the type of decoration at the end of a line as described in the documentation for the Java enumeration type org.bzdev.obnaming.misc.BasicStrokeParm.Cap.
• hasStrokeJoin. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: strokeJoin, whose value is either BEVEL, MITER, or ROUND. These values define how line segments are joined as described in the documentation for the Java enumeration type org.bzdev.obnaming.misc.BasicStrokeParm.Join.
• hasStrokeWidth. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: strokeWidth, whose value is the width of a stroke used to draw a path. The units are GCS units when gcsMode is true and user-space units when gcsMode is false or not defined.
• hasWindingRule. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: windingRule, whose value is WIND_EVEN_ODD or WIND_NON_ZERO.
• hasZorder. This is an iterative directive which will provide at most a single iteration. When present (i.e., when the iteration count is 1), there is a single directive: zorder, whose value is a long integer.
• pathItem. This is an iterative directive that will list a series of objects representing a path.

• pindex. The value is "1" for the initial MOVE_TO operation for a path and is incremented for each control point, spline point, or end-of-segment point, along the path, and for a final 'close' directive if there is one.
• type. This is the type of a point or operation along the path (MOVE_TO, SPLINE, CONTROL, SEG_END, or CLOSE).
• ltype. This is similar to the type directive, but substitutes CONTROL_POINT for CONTROL, and SPLINE_POINT for SPLINE. The directive ltype is useful for configuring an instance of the class org.bzdev.anim2d.AnimationLayer2DFactory.
• atype. This is is similar to type but with an alternative value defined by the user via a command-line argument that provides the name of a file mapping types to their replacement strings.
• optcomma. This provides an optional comma that, when used at the end of pathItem block, will result in a comma being inserted as separator between items. If a different separator a semicolon for example, is wanted one can use a construct such as $(+optcomma:endOC);$(endOC), which will replace the comma with a semicolon.
• xy. This is an iterative directive, with 0 or 1 iterations. It defines the following directives (the same ones as defined by the location directive) when the value of typeis MOVE_TO, SPLINE, CONTROL, or SEG_END:
  • x. The X coordinate of the point in graph coordinate space.
  • y. The Y coordinate of the point in graph coordinate space.
  • xp. The X coordinate of the point in image space.
  • yp. The Y coordinate of the point in image space, measured from top to bottom (the standard Java convention).
  • ixp. The X coordinate of the point in image space, rounded to the nearest integer.
  • iyp. The Y coordinate of the point in image space, measured from top to bottom (the standard Java convention) and rounded to the nearest integer.
  • ypr. The Y coordinate of the point in image space measured from bottom to top (the reverse of the standard Java convention, following the convention used in mathematics instead).
  • dist. When set, this provides the distance from the XY coordinates of the previous point to the XY coordinates of this point in GCS units.
  • distp. When set, this provides the distance from the XY coordinates of the previous point to the XY coordinates of this point in image space units.
  • idistp. When set, this provides the distance from the XY coordinates of the previous point to the XY coordinates of this point in image space units, but rounded to the nearest integer.
  • rad. When set, this provides the angle a line from the point represented by the previous row's XY coordinates to the point represented by this row's XY coordinates makes with the positive X axis. Units are radians with positive values in the counter-clockwise direction.
  • deg. When set, this provides the angle a line from the point represented by the previous row's XY coordinates to the point represented by this row's XY coordinates makes with the positive X axis. Units are degrees with positive values in the counter-clockwise direction.
  • radp. When set, this provides the angle a line from the point represented by the previous row's XY coordinates to the point represented by this row's XY coordinates makes with the positive X axis. Units are radians with positive values in the clockwise direction.
  • degp. When set, this provides the angle a line from the point represented by the previous row's XY coordinates to the point represented by this row's XY coordinates makes with the positive X axis. Units are degrees with positive values in the clockwise direction.
  When the type is CLOSE, the xy directive is not defined.
• hasParameterInfo. This is an iterative directive with 0 or 1 iterations. It will have a single iteration when the type is MOVE_TO, SEG_END, SPLINE, or CLOSE. An iteration defines the following directives:
  • hasSubvarname. This is an iterative directive with a 0 or 1 iterations. When it has 1 iteration, the directive subvarname will be defined.
  • subpathvar. The name of a subpath, if one exists. The iterative directive hasSubpathvar can be used to test if this directive is defined. For paths that are defined as a sequence of paths, this variable names an individual path in that sequence.
  • s. The distance from the start of a subpath, of the distance from the start of a path if there are no subpaths, for the current point along a path.
  • u. The value of the path parameter for a the subpath, or the path itself if the path does not have subpaths, for the current point along a path.

For example, the following template will create a set of statements suitable for use by ESP or ECMAScript (the template EPTS actually uses has less whitespace so that the output will contain fewer blank lines and will be indented properly for readability):

  $(items:endItems)
     $(location:endLocation)
        var $(varname) = {x: $(x), y: $(y)};
  $(endLocation)
  $(pathStatement:endPathStatement)
     var $(varname) = [
         $(pathItem:endPathItem)
            {type: "$(type)"
            $(xy:endXY), x: $(x), y: $(y)$(endXY)}$(optcomma)
         $(endPathItem)
        ];
  $(endPathStatement)
$(endItems)

Path-iterator templates

• area. This directive contains the area of the shape. If constructed from multiple paths, all of these paths must be closed paths: otherwise the value will be "NaN". The units are either user-space units or GCS units, depending on flags passed to epts. When the epts command contains the --gcs option, GCS units are used; otherwise user-space units are used.
• circumference. This directive contains the circumference of the shape. If constructed from multiple paths, all of these paths must be closed paths: otherwise the value will be "NaN". The units are either user-space units or GCS units, depending on flags passed to epts. When the epts command contains the --gcs option, GCS units are used; otherwise user-space units are used.
• pathLength. This directive contains the path length for the boundary of a shape, regardless of whether it encloses an area. The units are either user-space units or GCS units, depending on flags passed to epts. When the epts command contains the --gcs option, GCS units are used; otherwise user-space units are used.
• varname. This directive provides the name of the variable whose value is the path that the following directives describe.
• windingRule. This directive determines the winding rule. Its values are either WIND_EVEN_ODD or WIND_NON_ZERO. WIND_EVEN_ODD indicates that a point is inside a closed path if a ray drawn to infinity crosses path segments an odd number of times. WIND_NON_ZERO indicates that a point is inside a closed path if a ray drawn to infinity crosses segments drawn in the counterclockwise direction a different number of times than segments drawn in the clockwise direction.
• segments. This is an iterative directive that provides data for a sequence of path segments. A MOVE_TO segment sets the current point and the other path segments describe how to extend the path from the current point.

• type. This directive is always provided. Its value can be either SEG_CLOSE, SEG_MOVETO, SEG_CUBICTO, SEG_LINETO, or SEG_QUADTO.
• method. This directive is always provided. Its value can be either closePath, moveTo, lineTo, quadTo,or cubicTo. These are the names of the Java methods used to construct a path.
• hasClose. This is an iterative directive providing 0 or 1 iterations. When provided, it indicates that the path is to be closed, terminating at the position give by the last MOVETO operation. If necessary, a straight-line segment will be added to close the path.
• hasMoveTo. This is an iterative directive providing 0 or 1 iterations. When provided, it indicates that the path has a section that starts at a specific point whose coordinates are the values of the x0 and y0 directives.
• hasLineTo. This is an iterative directive providing 0 or 1 iterations. When provided, it indicates that the current segment is a straight line ending at a new current point whose coordinates are given by the values of the x0 and y0 directives.
• hasQuadTo. This is an iterative directive providing 0 or 1 iterations. When provided, it indicates that the current segment is a quadratic Bézier curve whose first control point is given by the values of the x0 and y0 directives, and whose final point (the new current point) is given by the values of the x1 and y1 directives.
• hasCubicTo. This is an iterative directive providing 0 or 1 iterations. When provided, it indicates that current segment is a cubic Bézier curve whose first control point is given by the values of the x0 and y0 directives, whose second control point is given by the values of the x1 and y1 directives, and whose final point (the new current point) is given by the values of the x2 and y2 directives.
• x0. This directive, when present, gives the X coordinate for a point that is either the starting point provided for a SEG_MOVETO operation, the ending point for a SEG_LINETO operation, or the first control point for a SEG_QUADTO or SEG_CUBICTO operation.
• y0. This directive, when present, gives the Y coordinate for a point that is either the starting point provided for a SEG_MOVETO operation, the ending point for a SEG_LINETO operation, or the first control point for a SEG_QUADTO or SEG_CUBICTO operation.
• x1 This directive, when present, gives the X coordinate for a point that is either the final point for a SEG_QUADTO operation of the second control point for a SEG_CUBICTO operation.
• y1. This directive, when present, gives the Y coordinate for a point that is either the final point for a SEG_QUADTO operation of the second control point for a SEG_CUBICTO operation.
• x2. This directive, when present, gives the X coordinate for a point that is the final point for a SEG_CUBICTO operation.
• y2. This directive, when present, gives the Y coordinate for a point that is the final point for a SEG_CUBICTO operation.

• has0 This is an iterative directive with 1 iteration that indicates that the directives x0 and y0 have non-empty values.
• has1 This is an iterative directive with 1 iteration that indicates that the directives x1 and y1 have non-empty values.
• has2 This is an iterative directive with 1 iteration that indicates that the directives x2 and y2 have non-empty values.

The command-line interface

If the epts command is run with no arguments or only --gui argument the, the program will open a dialog box asking for the name of an image file to open, an EPTS saved state to restore, or a script to run (which will use the default animation name a2d) as described above. To create a configuration file (the extension is "eptc"), one should either use a desktop action or a command-line option shown below.

There are several combinations of command-line arguments that are treated specially:

• --sessionConfig will open a dialog box that will allow a session to be configured.
• --templateConfig will open a dialog box that will allow template processing to be configured.
• --stackTrace --sessionConfig will open a dialog box that will allow a session to be configured. Stack traces will be included in various error messages.
• --stackTrace --templateConfig will open a dialog box that will allow template processing to be configured. Stack traces will be included in various error messages.
• --gui --stackTrace -- FILE will open the specified file. This file may be a saved-state file (extension epts), a session configuration file (extension eptc), a script, or an image file. For some error messages, a stack trace may be provided.
• --gui --stackTrace with no additional arguments will request an input file. This file may be a saved-state file (extension epts), a session configuration file (extension eptc), a script, or an image file. For some error messages, a stack trace may be provided.
• --gui -- FILE will open the specified file. This file may be a saved-state file (extension epts), a session configuration file (extension eptc), a script, or an image file.
• --gui with no additional arguments will open a dialog box that will ask for a file to read. This file may be a saved-state file (extension epts), a session configuration file (extension eptc), a script, or an image file.
• --stackTrace -- FILE will open an input file, treating it specially if it is a session configuration file. Some error messages will provide stack traces. The file can be either a session configuration file, a saved-state file, an image file, or a script.
• --stackTrace will ask for a file to open. The file can be either a session configuration file, a saved-state file, an image file, or a script.p
• -- FILE will open an input file, treating it specially if it is a session configuration file. The file can be either a session configuration file, a saved-state file, an image file, or a script.
• TCOPTIONS TCFILE will process a template-configuration file TCFILE in match mode provided that TCOPTIONS contains a -o option and no other options beside --, and --stackTrace.

If the epts command is run with multiple file-name arguments, the program's behavior depends on the file format for the first argument:

• if the argument is an EPTS saved-state file, whose file-name extension must be "epts", the state of a previous session will be restored. Additional arguments are allowed, and these must be script files. If the script files doe not have a standard extension for a scripting language, the -L option must be used to set the scripting language. The additional scripts will not be kept if the state is saved. Instead, they may be provided to enhance the current image. For example, the script resource:grid.js will overlay an image with a rectangular grid of lines. If the animation the script provides is not stored in a variable named a2d, the --animation option will also be needed.
• if the argument is an image file, the image it contains will be used as a background image. No additional arguments are allowed. To enhance an image by using a script, one should create a new saved state after configuring graph coordinate space. For example,

  epts image.png
  # Configure GCS
  # Save the session as (for example) saved.epts
epts --double spacing=10m saved.epts resource:grid.js
  

  The --double option is described below: it sets a scripting-language variable to a specified value with optional unit conversions. The URL scheme "resource" indicates that the script, in this case grid.js is provided by EPTS. When a script is added in this way, it augments the saved state temporarily, but the script will not be added to the saved state if the saved state is saved.
• if the argument is a file containing a script and the file's extension matches one used for that scripting language, the script will be run. The script can be partitioned into multiple files and these will be processed in the order lists. These scripts must provide an animation and assign it to the variable "a2d" (the name can be different if the --animation option is present). The animation will not be run by epts, and should not be run by scripts. The objects the animation initially creates will be used to generate the image. If the animation the script provides is not stored in a variable named a2d, the --animation option will also be needed. In this case, the scripts are saved if the session is saved. For example, running

  epts resource:grid.esp
  # Use the "Save" option in the "File" menu # to create grid.epts
  and then exit epts grid.epts

  will restart EPTS and re-run the script.
• if a non-option argument is a file whose extension is eptc or eptt, it must be the only non-option argument. Either can be proceeded by --gui, --stackTrace and/or -- in that order (all are optional). For the eptt case, this option may be proceeded by the arguments -o OUTFILE, in which case a GUI will not appear, which is desirable when the command is being run by software such as make that tracks file dependencies.

are EPTS saved-state files and restoring a session using these can be done using a computer's window system.

When run from the command line, a number of additional options are available. Specific categories of options are

• Scripting Options. These contain options specific to scripting.
• Template Options These contain options used with templates.
• Scrunner Options. These contain options used with scrunner program, whose configuration file is used by EPTS.

There are five options that do not fit into well-defined categories:

• --. This option simply indicates the end of options, and is provided in case a file name starts with a "-".
• --image IFILE. This option implies that a background image will be displayed. This option is not needed unless IFILE is either - or a saved-state file, but may be used to specify an image file if desired (a URI referencing an image can be used as well). When used with an image file, no arguments after the last option are allowed. The most common image formats are PNG and JPEG. These can use the file-name extensions "png" and "jpg" respectively. If the file name is literally "-", EPTS will create an image containing a solid background (the -w and -h options can be used to set the image width and height). The --animation option may not be used with this option if IFILE is not an EPTS saved state. When IFILE is an EPTS saved state for a saved state that is the argument for an --image option, paths and locations recorded in the saved state will be ignored, but additional scripts can be added so as to be saved if a saved-state file is created.
• --port PORT. When this flag is used, it sets the TCP port number for an embedded web server that will provide the on-line manual. The port number PORT must be a valid TCP port number (1 to 65535 inclusive, but some ports are reserved or require system privileges). If the port is 0 or if this option is not provided, the system will provide a port.
• --animation A2D. This option indicates that scripts will use the variable A2D to store the animation used to reference an image. The argument A2D is the name of a scripting-language variable whose value will be an instance of the class org.bzdev.anim2d.Animation2D. It will be used to produce an image by creating a snapshot of the objects that are currently defined in the animation and that are visible. The scripts will configure this object. The constructor for an Animation2D will determine the size of the image unless the --image option is also present, but the --image option can not be used with this option unless the argument for --image is an EPTS saved state.
• --gui. This option indicates that the program might be run without directly starting the program from a terminal window. The current working directory will be set to that containing the file specified by the first non-option argument, provided that the file is an image file or an EPTS saved state. In addition, error messages (with a couple of exceptions) will appear in windows rather than being printed to standard output. This is provided because when a program is started using a window system, the current working directory is often not the one containing its argument file and messages to standard output or standard error might not be visible to the user.
• --sessionConfig. This argument is recognized if it is the only argument used or if it is preceded by the --stackTrace argument; otherwise an error will be generated. It is intended for use by window systems for starting EPTS in a particular mode. When this option is provided, EPTS will first show the user a dialog box that allows the user to provide data for various scripting-related arguments. The user will be given an opportunity to save the configuration before proceeding to run EPTS with the corresponding arguments.

Units

• nm for distances measured in nanometers.
• um for distances measured in microns.
• mm for distances measured in millimeters.
• cm for distances measured in centimeters.
• m for distances measured in meters (the conversion factor is 1.0 in this case).
• km for distances measured in kilometers.
• in for distances measured in inches.
• ft for distances measured in feet.
• yd for distances measured in yards.
• mi for distances measured in miles.

      epts --double spacing=10ft  saved.epts resource:grid.js

Scripting options

• --boolean NAME=BVALUE. The argument consists of two parts. NAME is the name of a scripting-language variable and BVALUE is a boolean represented by the value true or false for that variable. The variable will be set before any script is run.
• --double NAME=DVALUE. The argument consists of two parts. NAME is the name of a scripting-language variable and DVALUE is a real number that provides the corresponding value for that variable. The variable will be set before any script is run.
• --height HEIGHT. The height in points for an image with one pixel per point that represents a drawing surface. If not provided, a default of 1024 will be used.
• --int NAME=IVALUE. The argument consists of two parts. NAME is the name of a scripting-language variable and IVALUE is an integer that provides the corresponding value for that variable. The variable will be set before any script is run.
• --string NAME=SVALUE. The argument consists of two parts. NAME is the name of a scripting-language variable and SVALUE is a string that provides the corresponding value for that variable. The variable will be set before any script is run.
• --width WIDTH. The width in points for an image with one pixel per point that represents a drawing surface. If not provided, a default of 1024 will be used.

Template options

• --class CLASSNAME. This option applies when the --tname option is used, and provides a class name for table templates that generate Java code (e.g., a single Java class definition). The argument CLASSNAME is the simple name for a class.
• --elevate. This option applies when the --pname option is set and is ignored otherwise. When set, the degree of linear and quadratic Bézier curve segments will be elevated so that all segments are cubic Bézier curve segments.
• --fill-color COLOR. This option is used for table templates and applies to the path specified by the following --tname option. It sets the fill attribute to COLOR in an SVG path and the parameter fillColor to COLOR as the only element in a hasFillColor iterative parameter for table templates. When used with animation-object factories, it will determine if there is a drawColor.css subparameter. This option applies to a path specified by the next --tname option. The value of COLOR can be any color specification accepted by SVG (the same as those defined by the CSS2 specification). A value of none indicates that no color is specified and the path will not be drawn. Named colors are listed at <https://www.w3.org/TR/css-color-3/#svg-color>. A # followed immediately by 6 hexadecimal digits gives the RGB values (two hexadecimal digits each in that order). One can also use the expression rgb(R,G,B) where the "red" component R , the green component G, and the blue component B vary from 0 to 255 or 0% to 100%. Similarly, the expression rbga(R,G,B,A) can be used, where the alpha component A varies from 0 to 1 and the other components are the same as for the RGB case. An HSL (Hue, Saturation, Lightness) specification can also be used: hsl(H,S,L), where H is a real number in the range [0, 360), S is a real number in the range [0%, 100%], and L is a real number in the range [0%, 100%]. With an alpha channel, the HSL syntax is hsla(H,S,L,A), where A is a real number in the range [0, 1].
• --flatness FLATNESS. This option applies when the --pname option is set and is ignored otherwise. When FLATNESS is zero,he --limit option determines the number of times a segment will be partitioned. Otherwise control points must deviate from a straight line along each segment by at most the value of FLATNESS.
• --gcs. This option applies when the --pname option is set and is ignored otherwise. When present, it indicates that coordinates will be in GCS units. Otherwise user-space or image space units are used.
• --limit LIMIT. This flag applies when the --pname option is used and is ignored otherwise. This parameter limits the amount of recursion used when paths are split to meet a flatness criteria. When LIMITis zero, paths will not be partitioned. Otherwise the path will be split recursively until the flatness limit is reached, with LIMIT restricting the recursion depth.
• --map MAPFILE. The file MAPFILE is a text file (UTF-8 encoded) whose entries are a series of lines. Each line contains a token that is the name of an enumeration constant whose type is org.bzdev.geom.SplinePathBuilder.CPointType, followed by whitespace separating that token from its replacement value. Any trailing whitespace will be removed from the replacement. Valid token values are MOVE_TO, SPLINE, CONTROL, SEG_END, or CLOSE. In templates, the tokens become the value for $(type) and the replacements become the value for $(atype). If a mapping is not defined, the replacement is the same as the original. The argument MAPFILE can be either a file name or a URL. If the file named is a relative file, the name is resolved using the current working directory when EPTS started. This may not be the current working directory while EPTS is running as the current working directory may be changed when an EPTS file (one with a .epts extension) is processed. If MAPFILE starts with the string "resource:", "file:", "http:", "https:", or "ftp", then MAPFILE is assumed to be a URL pointing to the object to read.
• -o OUTFILE. This option specifies the name of the output file for template processing. If it is a relative file, it will be resolved against the current working directory that existed when EPTS was started. If the file name is "-", the output will be sent to standard output. When a -o is present (it is required by the --svg, --svg-mm, and --template options), there must be a single filename argument: the name of an EPTS file (e.g., saved.epts).
• --package PACKAGENAME. This option applies when the --tname option is used, and provides a class name for table templates that generate Java code (e.g., a single Java class definition). The argument PACKAGENAME is the fully-qualified class name for a Java package.
• --pname PNAME. This option selects a variable name, PNAME, that must match the name of a path. It is used with templates that use the path-iterator format. PNAME may also consist of an identifier providing a variable name, immediately followed by a ":", in turn followed by a series of comma-separated path names. This in effect creates a path with a new name that is a concatenation of paths specified in EPTS's table. The main use of this variant is to create shapes that may have holes in them. The options --elevate, flatness, --gcs, limit, and/or --straight may be used when a --pname option is present. The options --pname and --tname are mutually exclusive.
• --public. This option applies when the --tname option is used and indicates that any Java class being defined by a template should be a public class.
• --straight. This option applies when the --pname option is set and is ignored otherwise. When set, the selected path will be flattened and converted to straight-line segments.
• --stroke-color COLOR. This option is used for table templates and applies to the path specified by the following --tname option. It sets the stroke attribute to COLOR in an SVG path and the drawColor parameter to COLOR as the only element in a hasDrawColor iterative parameter for use in table templates. Built-in templates that configure animation-object factories use these to set the drawColor.css subparameter. This option applies to a path specified by the next --tname option. The value of COLOR can be any color specification accepted by SVG (the same as those defined by the CSS2 specification). A value of none indicates that no color is specified and the path will not be drawn. Named colors are listed at <https://www.w3.org/TR/css-color-3/#svg-color>. A # followed immediately by 6 hexadecimal digits gives the RGB values (two hexadecimal digits in that order). One can also use the expression rgb(R,G,B) where the "red" component R , the green component G, and the blue component B vary from 0 to 255 or 0% to 100%. Similarly, the expression rbga(R,G,B,A) can be used, where the alpha component A varies from 0 to 1 and the other components are the same as for the RGB case. An HSL (Hue, Saturation, Lightness) specification can also be used: hsl(H,S,L), where H is a real number in the range [0, 360), S is a real number in the range [0%, 100%], and L is a real number in the range [0%, 100%]. With an alpha channel, the HSL syntax is hsl(H,S,L,A), where A is a real number in the range [0, 1].
• --stroke-cap VALUE. This option is used for table templates and applies to the path specified by the following --tname option. Its values can be one of the following: butt, which ends enclosed subpaths and dash segments with no added decoration; round, which ends enclosed subpaths and dash segments with a round decoration that has a radius equal to half the width of the stroke; and square, which ends enclosed subpaths and dash segments with a square projection that extends beyond the end of the segment by a distance equal to half of the stroke width.
• --stroke-dash-incr VALUE. This option is used for table templates and applies to the path specified by the following --tname option. The argument VALUE is the length assigned to a "-" or " " in a dash pattern. VALUE is specified in graph coordinate space when the option --stroke-gcs-mode is true; otherwise it is specified in user-space or image space units.
• --stroke-dash-pattern VALUE. A dash pattern specifies how dashes are drawn. VALUE will be a sequence of minus signs ("-") and spaces (" "), starting with a "-". The length of N "-" characters in a row or N spaces in a row is N multiplied by the dash increment, and corresponds to the length of a stroke or gap respectively. The dash pattern will repeat. VALUE is specified in graph coordinate space when the option --stroke-gcs-mode is true; otherwise it is specified in user-space or image space units. When provided, a dash pattern can consist only of "-" characters and otherwise must start with a "-" and end with a " ".
• --stroke-dash-phase VALUE. This option is used for table templates and applies to the path specified by the following --tname option. VALUE is offset to the start of the dash pattern. VALUE is specified in graph coordinate space when the option --stroke-gcs-mode is true; otherwise it is specified in user-space or image space units.
• --stroke-gcs-mode BOOLEAN. This option is used for table templates and applies to the path specified by the following --tname option. The value BOOLEAN can be true or false. This option sets the stroke.gcsMode subparameter for table templates, and indicates if stroke dimensions are in GCS units or user-space units (the default). For GCS units, the value must be true.
• --stroke-join VALUE. This option is used for table templates and applies to the path specified by the following --tname option. Its values can be one of the following: bevel, which joins path segments by connecting the outer corners of their wide outlines with a straight segment; miter, which joins path segments by extending their outside edges until they meet; round, which joins path segments by rounding off the corner at a radius of half the line width.
• --stroke-miter-limit VALUE. This option is used for table templates and applies to the path specified by the following --tname option. The miter limit is the limit such that a line join is trimmed when the ratio of miter length to stroke width is greater than this value. The miter length is the diagonal length of the miter, which is the distance between the inside corner and the outside corner of the intersection. The smaller the angle formed by two line segments, the longer the miter length and the sharper the angle of intersection. The default miter-limit value of 10.0 causes all angles less than 11 degrees to be trimmed. Trimming miters converts the decoration of the line join to a bevel. This value applies only to a line join that has a miter join decoration and must be larger than or equal to 1.0. VALUE is specified in graph coordinate space when the option --stroke-gcs-mode is true; otherwise it is specified in user-space or image space units.
• --stroke-width WIDTH. This option is used for table templates and applies to the path specified by the following --tname option. It sets the stroke-width attribute to WIDTH in an SVG path. The value of WIDTH is the width in graph coordinate space when the option --stroke-gcs-mode is true; otherwise it is the width in user-space or image space units.
• --svg and --svg-mm. Either of these options indicates that the output will be an SVG (Scaleable Vector Graphics) file:
  • --svg is used for an SVG file in which the image's width and height are in units of points (1/72 inches), the same units used in user space.
  • --svg-mm is used for an SVG file in which the image's width and height are in units of millimeters (mm). The width and height of the EPTS window, as viewed on a screen, is scaled to the corresponding distance in graph coordinate space, expressed in units of millimeters. For example, if the height and width parameters when EPTS is started are 1000, and graph coordinate space is configured so that a distance of 5 in user space corresponds to 1 mm in graph coordinate space, then the SVG image will have a height and width of 200 mm. The --svg-mm option is particularly useful when generating files for services such as a laser-cutting service.
  In either case, the option -o is required and at least one --tname option should be present. The options --fill-color, --stroke-color, --stroke-cap, --stroke-dash-incr, --stroke-dash-phase, --stroke-dash-pattern, --stroke-gcs-mode, --stroke-miter-limit, stroke-join, --stroke-width, and --winding-rule, may be used (at least one will typically be provided). A --template option must not be provided.
• --tdef DEFNAME=DEFVALUE. This option adds template key-value pairs for use by the template processor in addition to the ones defined by EPTS. The argument DEFVALUE is a string. If empty, the definition is ignored. Otherwise, DEFNAME can be a name or a pair of names separated by a colon. In the latter case, the first name in the pair is treated as an iteration directive with a single iteration, mimicking an 'if' statement, and the second name is the name to which the value will be assigned. For example, the argument --tdef hasCount:count=30 will result in the template text

  $(hasCount:endCount)count = $(count);$(endCount)

  being changed into

  count = 30

  when this --tdef is present and into empty text when this --tdef is not present. A number of names are reserved: class, hasPackage, height, items, optSpace, package, paths, public, and width. Some of these reserved names refer to iterative directives, and each iterative directive will define additional directives during an iteration. These will override a global directive with the same name during an iteration but will not alter such a global directive.
• --template:RESOURCE. This option is a shortcut that behaves like the option --template resource:RESOURCE.
• --template TFILE. This option may not be used with the --svg option, but as with the --svg option, the -o option is required. When TFILE starts with the string "resource:", "file:", "http:", "https:", or "ftp", TFILE is assumed to be a URL. Otherwise is is assumed to be the name of a file. The syntax of a template is describe in the section of this manual entitled "Templates". For the resource protocol, the template is embedded in the EPTS application. and these are described above in the section describing built-in templates. The supported table templates are resource:ECMAScriptLayers, resource:ECMAScriptLocations, resource:ECMAScriptPaths, and resource:ECMAScript. These must be used without the --pname option. Supported path-iterator templates are resource:area, resource:areaVars, resource:circumference, resource:circumferenceVars resource:pathlength, resource:pathlengthVars, and resource:SegmentsCSV.< These must be used with the --pname option.
• --tname TNAME. This option's argument TNAME provides the name of a variable that names a path. When this option is provided, a table template must be used and the keymap is the table keymap as described by the manual page epts(5) and by the on-line manual for epts. TNAME may be an existing identifier for a path or a location in an EPTS table, or it may consist of an identifier, immediately followed by a ":", in turn followed by a series of comma-separated path names. This in effect creates a path with a new name that is a concatenation of paths specified in EPTS's table. Before each --tname option, there may be a --winding-rule option. The options --pname and --tname are mutually exclusive.
• --web. The --port option should also be used to provide a non-zero port number. This option will start an embedded web server allowing the manual to be shown.
• --winding-rule RULE. This option, when present, adds a winding rule for use with table templates when the --tnameoption is used, and must precede that option. After a --tnameoption is seen, the winding rule removed. The values of RULE may be evenodd or nonzero. The --winding-rule option sets a template-table keymap directive as described in the documentation for epts(5) and in the on-line manual.
• --zorder VALUE. This option is used for table templates and applies to the path specified by the following --tname option. This option's argument VALUE provides the Z-order for a path.
• --. End of options. This can be used if file names start with the character '-'. Otherwise it is not necessary.

Scrunner options

• --add-modules SPEC. This option's argument is a comma-separate list of module names. Multiple instances of this option can be used as well. The list must not contain whitespace. It is used primarily in cases in which the only use of a module occurs in scripts. It is not necessary when a module provides a factory as that is explicitly indicated in the module definition.
• --classpathCodebase SPEC. This option's argument is treated the same of the argument for the --codebase option below, but adds code bases to the class path instead of the module path. This option is provided for cases in which a JAR file cannot be used on the module path.
• --codebase SPEC. This option allows additional code bases to be available to the JVM and places these on the module path. As a result, each codebase must be a modular JAR file. Any number of --codebase options may be provided, and each option can contain multiple code bases with the character '|' used as a separator. As a special case, if there are n '|' characters in a row, they will be placed by floor(n/2) '|' characters and when n is odd, the final '|' is used as a separator. As a result, except for the first component of a code-base path, components may not start with a '|'. A code base is specified by either a URL or a path name of a file in (local) file system. If there is a ':' in the file name and the preceding characters are consistent with a protocol name in a URL, the file name will be treated as a URL. In this case, use a "file:" URL to specify the code base. Several characters are treated specially. A leading "~" followed by the name separator ("/" for Unix) is expanded to the user's home directory. A file name consisting only of "~" is replaced with the user's home directory. A leading "~~" is replaced with "~", and a leading "..." followed by the name separator ("/" for Unix) is replaced by the directory in which the BZDev class library's JAR file is located. If an EPTS session is saved, the saved file will contain the files and directories provided by the --codebase options, but for security reasons the user will be asked to confirm all codebases except those in the same directory as the BZDev class library. Finally, the substitutions for '|', '~', and '...' (followed by the file-name separator) apply only to the --codebase option, not to file-name arguments that appear after the last option.
• -DNAME=VALUE. This option defines a system property whose name is NAME and whose value is VALUE.
• --dryrun. This options simply prints the java command that will be used to start the JVM and run the program. It is useful primarily for debugging.
• -JOPTION. The string OPTION is turned into an option passed to the 'java' command used to start the JVM. It can be used, for example, to increase the memory available to the JVM. If the option starts with a leading '-', that must be provided explicitly.
• -L LNAME. When scripting is used, this option explicitly indicates a scripting language. ESP (and currently ECMAScript) are always supported.
• --resourcePathNAMES. The string NAMES is a series of URLS or file names separated by the '|' character. As a special case, if there are n '|' characters in a row, they will be placed by floor(n/2) '|' characters and when n is odd, the final '|' is used as a separator. As a result, except for the first component of a code-base path, components may not start with a '|'. If there is a ':' in the file name and the preceding characters are consistent with a protocol name in a URL, the file name will be treated as a URL. In this case, use a "file:" URL to specify the resource. In addition, if "~/" appears at the start of a file name, "~" will be replaced with the user's home directory, a file that is just "~" will be replaced with the user's home directory, and a leading "~~" is replaced with one "~". Multiple --resourcePath options can be used.

CLI examples

The following examples illustrate common cases.

• epts saved.epts
  Start EPTS, restoring its state to one saved in a previous session.
• epts tplate.eptt
  Start EPTS, restoring the state for template processing that was previously saved.
• epts saved.epts resource:grid.js
  Start EPTS, restoring its state to one saved in a previous session and use a script to overlay a grid on top of the image. Points and paths will be placed over the grid. The image in this case must be created by a script, and the built-in script grid.js assumes that the animation used to create the grid is named a2d. The grid will not be part of the saved-state file if the session is saved.
• epts --double spacing=10ft --image s.epts resource:grid.js
  Start EPTS, generating the background image specified by the saved-state file saved.epts, but not restoring paths and points created in previous sessions due to the presence of the --image argument. The background image will be augmented with additional scripts specified on the command line, in this case the build-in script (grid.js) that adds a grid overlaying the image. The grid spacing corresponds to 10 feet in graph coordinate space. If the session is saved, the new saved-state file will include the previously defined scripts, the new script defined on the command line, and the value for the variable spacing (the value used is the distance in meters corresponding to 10 feet).
• epts --codebase foo.jar saved.epts
  Start EPTS, restoring its state to one saved in a previous session, adding a jar file foo.jar to EPTS's code base.
• epts image.png
  Start EPTS with an image preloaded as its background.
• epts --animation anim commands.js
  Start EPTS and run the script provided in commands.js to generate an image from an animation anim (an instance of org.bzdev.anim2d.Animation2D). In this case, a saved-state file will rerun the script.
• epts --resourcePath images commands.esp
  Start EPTS and run the script provided in commands.js to generate an image from an animation a2d (an instance of org.bzdev.anim2d.Animation2D). In this case, a saved-state file will rerun the script. The --resourcePath option allows external images to be included. For example, the following ESP script

  import(org.bzdev.anim2d, [
      Animation2D,
      AnimationLayer2D,
      AnimationLayer2DFactory]);
  
  var frameWidth = 719;
  var frameHeight = 375;
  
  var a2d = new Animation2D(scripting,
                            frameWidth,
                            frameHeight,
                            1000.0, 40);
  a2d.setRanges(0.0, 0.0, 0.0, 0.0,
                1.0, 1.0);
  
  a2d.createFactories("org.bzdev.anim2d", {
      alf: "AnimationLayer2DFactory"});
  ###
  alf.createObject("background", [
      {visible: true},
      {zorder: 0},
      {withPrefix: "object", withIndex: [
          {type: "IMAGE",
           imageURL:
               "resource:background.png",
           refPoint: "LOWER_LEFT",
           x: 0.0, y: 0.0,
           imageInGCS: false
          }
      ]}]);
      

  will include a copy of the image in the file background.png from the images directory. Additional scripts such as resource:grid.esp can be added as well.
• epts --codebase foo.jar --animation anim commands.js
  Start EPTS and run the script provided in commands.js to generate an image from an animation a2d (an instance of org.bzdev.anim2d.Animation2D). The file foo.jar contains additional classes needed by the script. The --codebase option will be needed when restarting EPTS using a saved state created when this command is being run.
• epts -o out.js --template:ECMAScript saved.epts
  Run EPTS without a GUI to generate a file out.js containing a series of ESP or ECMAScript statements containing the contents of the EPTS table.
• epts -o out.svg --svg --fill red --pname s:c1,c2 saved.epts
  Run EPTS without a GUI to generate an SVG file out.svg containing a shape sconsisting of two curves (c1 and c2) defined in the EPTS table. The table is the one defined by the file saved.epts
• epts -o - --gcs --template:area -pname s:c1,c2
  Run EPTS without a GUI to compute the area of a shape bounded by the curves c1 and c2. The area is in GCS units.
• epts -o output.svg tplate.eptt
  Run EPTS, restoring the state for template processing (configured for generating an SVG file) that was previously saved but replacing the name of the output file. The GUI will not be started. For this option to work properly, the eptt file must be in the current working directory.

If scrunner has been installed, the following ESP script (ESP is scrunner's default scripting language—a minimal scripting language that uses the Java streams package for iteration) will describe a path:

#!/usr/bin/scrunner -sE:true
import (org.bzdev.math.Functions);
import (org.bzdev.io.CSVWriter);

var w = new CSVWriter(global.getWriter(), 3);
var x0 = -15.0;
w.writeRow("MOVE_TO","" + x0, "" + 10*J(0, x0));

IntStream.rangeClosed(1, 100)
  .mapToDouble(function(i) {x0 + 0.3*i})
  .forEachOrdered(function(x) {
      w.writeRow("SPLINE", "" + x, "" + 10*J(0,x));
  });

w.flush();
w.close();
    

A path generated by reading points from the script above is shown in the following figure:

Scripting

When image sizes are known and scripts are being run, the scripting-language variable epts will have a non-null value and will provide several methods:

• epts.getWidth() to determine the frame width in user-space units.
• epts.getHeight() to determine the frame height in user-space units.
• epts.hasDistances() to determine if user-space and graph-coordinate-space distances are valid (true if valid, false if not).
• epts.getUserDist() to determine a user-space distance.
• epts.getGCSDist() to determine a corresponding graph-coordinate-space distance.
• epts.getRefPointName() to determine location of the reference point (the value is an enumeration constant defined by org.bzdev.graphs.RefPointName.
• epts.getXOrigin() to determine the X value in graph coordinate space for the reference point.
• epts.getYOrigin() to determine the Y value in graph coordinate space for the reference point.
• epts.getXFract() to determine the fractional distance from the left edge of a graph's range to its right edge. The values returned can be either 0.0, 0.5, or 1.0 and match the RefPointName enumeration.
• epts.getYFract() to determine the fractional distance from the lower edge of a graph's range to its upper edge. The values returned can be either 0.0, 0.5, or 1.0 and match the RefPointName enumeration.

if (typeof epts === 'undefined' || epts == null) {
    var frameWidth = 1024;
    var frameHeight = 1024;
} else {
    var frameWidth = epts.getWidth();
    var frameHeight = epts.getHeight();
}
var a2d = new Animation2D(scripting, frameWidth, frameHeight);

After an animation is created, one will typically create animation factories and use these factories to create animation objects that can be displayed. In particular, animation layers can be used to draw simple geometrical figures, figures based on paths, and can scale and place images. The normal sequence of calling the animation's methods initFrames, scheduleFrames and run are skipped: EPTS will iterate through the animation's objects using their Z-order and write them to a graph, thereby creating a background.

To use EPTS in developing animations, one can use templates to create ESP or ECMAScript code that will provide paths or in some cases shapes. There will be a series of files that can then be used by scrunner. Programs such as make that track file dependencies can be used to run EPTS with template options.

Built-in scripts

• resource:grid.js overlays a rectilinear grid as a representation of a Cartesian coordinates. The script uses the ECMAScript scripting language.
• resource:grid.esp overlays a rectilinear grid as a representation of a Cartesian coordinates. The script uses the ESP scripting language.
• resource:polar.js overlays a polar grid as a representation of polar coordinates. The script uses the ECMAScript scripting language.
• resource:polar.esp overlays a polar grid as a representation of polar coordinates. The script uses the ESP scripting language.

The grids the scripts display can be controlled by setting various EMCAScript variables. This is done using the CLI options

• --boolean. This must be used for variables whose values are either true or false.
• --double. This must be used for variables whose values are double-precision numbers
• --int. This must be used for variables whose values are integers (Java int or long values).
• --string. This must be used for variables whose values are strings.

As stated in the Scripting Options section of this manual, each of these options takes an argument of the form VARIABLE=VALUE, where VARIABLE is one of the variables listed the sections describing Cartesian-grid scripts and polar-grid scripts, and VALUE is the corresponding value. The variables frameWidth, frameHeight, userDist, gcsDist, xorigin, yorigin, xfract, and yfract are used by both scripts with the same meaning. They are used by these scripts only if an animation has to be created by them.

Cartesian-grid script

• frameWidth—an integer giving the width of the background image that will be created. The default is 1920. The value is ignored if the animation was created by another script.
• frameHeight—an integer giving the height of the background image that will be created. The default is 1080. The value is ignored if the animation was created by another script.
• userdist—a double giving a reference distance in user space. The default is 1.0. The ratio userdist/gcsdist is the scaling factor for converting distances in graph coordinate space to user space. The value is ignored if the animation was created by another script.
• gcsdist—a double giving a reference distance in graph coordinate space. The default is 1.0. The ratio userdist/gcsdist is the scaling factor for converting distances in graph coordinate space to user space. The value is ignored if the animation was created by another script.
• xorigin—a double giving the X coordinate in graph coordinate space for the frame's reference point. The default is 0.0. The value is ignored if the animation was created by another script.
• yorigin—a double giving the Y coordinate in graph coordinate space for the frame's reference point. The default is 0.0. The value is ignored if the animation was created by another script.
• xfract—a double giving the fraction of the frame width at which the reference point appears (0.0 is the left edge and 1.0 is the right edge). The default is 0.0. The value is ignored if the animation was created by another script.
• yfract—a double giving the fraction of the frame height at which the reference point appears (0.0 is the lower edge and 1.0 is the upper edge). The default is 0.0. The value is ignored if the animation was created by another script.
• spacing—a double giving the grid spacing in graph-coordinate space units. If not provided explicitly or if the value is null, 0.0, or negative, the default is computed by taking the minimum of the frame width and frame height, converting that minimum to graph coordinate space units, then dividing by 10, and finally finding the largest power of 10 that is not larger than this value. The grid lines will appear at X or Y coordinates that are an integral multiple of the spacing.
• subspacing—the number of subspacings per spacing for a finer grid. if undefined or 1, the value is ignored. In practice, values that create a subgrid are either 2, 4, 5, or 10. The value must be an integer.
• axisColor—the axis color provided as a CSS string, null or undefined for the default.
• spacingColor—the spacing color provided as a CSS string, null or undefined for the default.
• subspacingColor—the subspacing color provided as a CSS string, null or undefined for the default.
• strokeWidth—a double giving the width of the stroke used to create grid lines; undefined or null for a default.
• gridZorder—an integer giving the Z-order to use for the object that creates the grid. The default is the javascript value java.lang.Long.MAX_VALUE (2⁵³ - 1).
• plainBackgroundColor—a string providing CSS the color for the background when no image or animation is provided. The default value is "white".

Polar-grid script

• frameWidth—an integer giving the width of the background image that will be created. The default is 1920. The value is ignored if the animation was created by another script. If undefined or null, the default will be used.
• frameHeight—an integer giving the height of the background image that will be created. The default is 1080. The value is ignored if the animation was created by another script. If undefined or null, the default will be used.
• userdist—a double giving a reference distance in user space. The default is 1.0. The ratio userdist/gcsdist is the scaling factor for converting distances in graph coordinate space to user space. if undefined or null, the default will be used.
• gcsdist—a double giving a reference distance in graph coordinate space. The default is 1.0. The ratio userdist/gcsdist is the scaling factor for converting distances in graph coordinate space to user space. If undefined or null, the default will be used.
• xorigin—a double giving the X coordinate in graph coordinate space for a reference point in the frame. The default is 0.0. The value is ignored if the animation was created by another script. if undefined or null, the default will be used.
• yorigin—a double giving the Y coordinate in graph coordinate space for a reference point in the frame. The default is 0.0. The value is ignored if the animation was created by another script. If undefined or null, the default will be used.
• xfract—a double giving the fraction of the frame width at which the reference point appears (0.0 is the left edge and 1.0 is the right edge). The default is 0.0. The value is ignored if the animation was created by another script. If undefined or null, the default will be used.
• yfract—a double giving the fraction of the frame height at which the reference point appears (0.0 is the lower edge and 1.0 is the upper edge). The default is 0.0. The value is ignored if the animation was created by another script. If undefined or null, the default will be used.
• fractional—true if the grid origin's coordinates (gridXOrigin, gridYOrigin) are a fraction of the position in the frame (excluding offsets); false if absolute values in graph coordinate space are used. If undefined or null, a default will be used.
• gridXOrigin—a double giving the X component of the grid's origin. When fractional is true, the value is a fraction of the position in the frame, excluding offsets, in the X direction. When false, it is the X coordinate of the origin for a polar coordinate grid, given in graph-coordinate-space units. If undefined or null, a default value will be used.
• gridXOrigin—a double giving the Y component of the grid's origin. When fractional is true, the value is a fraction of the position in the frame, excluding offsets, in the Y direction. When false, it is the Y coordinate of the origin for a polar coordinate grid, given in graph-coordinate-space units. If undefined or null, a default value will be used.
• radialSpacing—a double giving the radial spacing for concentric circles; null, undefined, 0.0 or negative for a default.
• angularSpacing—the angular spacing in degrees for radial lines. The value should be a divisor of 90 degrees or either null or undefined for a default.
• gridColor—the grid-line color provided as a CSS string, undefined or null for the default.
• strokeWidth—a double giving the width of the stroke used to create grid lines; undefined or null for a default.
• gridZorder—an integer giving the Z-order to use for the object that creates the grid. The default is the javascript value java.lang.Long.MAX_VALUE (2⁵³ - 1).
• plainBackgroundColor—a string providing CSS the color for the background when no image or animation is provided. The default value is "white".

Saved-state file format

    <?xml version="1.1" encoding="UTF-8"?>
    <!DOCTYPE images PUBLIC "-//BZDev//EPTS-1.0//EN"
              "resource:org/bzdev/epts/epts-1.0.dtd">
    <epts xmlns="http://bzdev.org/DTD/epts-1.0">

    </epts>

1. An image element.
2. An optional codebase element.
3. An optional modules element.
4. An optional classpath element.
5. An optional scripting element.
6. An optional targetList element.
7. A gcsconfig element.
8. A table element.
9. An optional filters element

The image element

• width. The value of this attribute is an integer giving the width in pixels of an image that will be used as a background.
• height. The value of this attribute is an integer giving the height in pixels of an image that will be used as a background.
• imageURIExists. The value of this attribute is true or false. When true, the following targetList element will contain a single argument giving the URI for an image to display. Otherwise the following targetList arguments will contain the URIs for scripts that will be loaded. If this attribute is missing, the default value is false.

The codebase element

The modules element

The classpath element

The scripting element

• animation. The value of this attribute is the name of a scripting-language variable that will be bound to an instance of the class org.bzdev.anim2d.Animation2D that will be used to create an image.
• language. The value of this attribute is the name of the scripting language (e.g., ESP or ECMAScript).

The binding element

• name. The value of this attributes is the name of a scripting-language variable to which a value will be bound.
• type. The value of this attribute provides the Java type of a scripting-language variable, and can be int for integer values, double for real numbers, or String for strings.

The targetList element

The protocol portion of the URL can contain the following:

• file (a file on the local file system)
• http (a resource obtained via an HTTP GET request).
• https (a resource obtained via a secure HTTP GET request).
• ftp (a resource obtained via FTP).
• jar (an resource in a JAR file).
• resource (a resource in the application's code base).

The gcsconfig element

• unitIndex. The value is an integer indicating the type of units for GCS distances:
  • 0. Distances are in custom units.
  • 1. Distances are in nanometers (nm).
  • 2. Distances are in micrometers (um).
  • 3 Distances are in millimeters (mm).
  • 4. Distances are in centimeters (cm).
  • 5. Distances are in meters (m).
  • 6. Distances are in kilometers (km).
  • 7. Distances are in inches.
  • 8. Distances are in feet.
  • 9. Distances are in yards
  • 10. Distances are in miles.
• unitIndexRP. The value is an integer indicating the type of units for reference-point X-Y coordinates:
  • 0. Distances are in custom units.
  • 1. Distances are in nanometers (nm).
  • 2. Distances are in micrometers (um).
  • 3 Distances are in millimeters (mm).
  • 4. Distances are in centimeters (cm).
  • 5. Distances are in meters (m).
  • 6. Distances are in kilometers (km).
  • 7. Distances are in inches.
  • 8. Distances are in feet.
  • 9. Distances are in yards
  • 10. Distances are in miles.
  This attribute is optional for backwards-compatibility reasons. The default is 0.
• refPointIndex. The value is an integer indicating the reference point:
  • 0. The reference point is at the upper left corner of the image.
  • 1. The reference point is at the center of the upper edge of the image.
  • 2. The reference point is at the upper right corner of the image.
  • 3. The reference point is at the center of the left edge of the image.
  • 4. The reference point is at the center of the image.
  • 5. The reference point is at the center of the right edge of the image.
  • 6. The reference point is at the lower left corner of the image.
  • 7. The reference point is at the center of the lower edge of the image.
  • 8. The reference point is at the lower right corner of the image.
• userSpaceDistance. A distance in user space.
• gcsDistance. A distance in graph coordinate space corresponding to the user-space distance, measured in the units specified by the unitIndex attribute.
• xrefpointGCS. The X coordinate of the reference point in graph coordinate space, given in the units specified by the unitIndexRP attribute.
• yrefpointGCS. The Y coordinate of the reference point in graph coordinate space, given in the units specified by the unitIndexRP attribute.

The table element

• varname. This attribute is present when the type attribute has the value PATH_START. Its value is the name of a variable. It should be one acceptable to Java and to any scripting language that will be used.
• type. This attribute is always present. Its value can be one of the following:
  • LOCATION. The row represents a location. The attributes x, y, xp, and yp must be provided.
  • PATH_START. The row represents the start of a path.
  • PATH_END. The row represents the end of a path.
  • MOVE_TO. The row represents a MOVE_TO operation. The attributes x, y, xp, and yp must be provided.
  • SPLINE. The row represents a knot on a spline, excluding its end points. The attributes x, y, xp, and yp must be provided.
  • CONTROL. The row represents a control point. The attributes x, y, xp, and yp must be provided.
  • SEG_END. The row represents the end of a segment The attributes x, y, xp, and yp must be provided.
  • CLOSE. The row indicates that the path will be closed. A path is closed by drawing a straight line segment from the last SEG_END point to the first MOVE_TO point with one exception: if a path starts with a MOVE_TO operation and otherwise contains only SPLINE points, a closed spline will be created.
• x. The value of this attribute is an X coordinate in graph-coordinate-space units (meters or custom units).
• y. The value of this attribute is an Y coordinate in graph-coordinate-space units (meters or custom units).
• xp. The value of this attribute is the X coordinate in user-space units, measured from the lower-left corner of the image, with positive values pointing right.
• yp. The value of this attribute is the Y coordinate in user-space units, measured from the lower-left corner of the image, with positive values pointing up.

The filters element

The filters element does not have any attributes and just contains a possibly empty sequence of filter elements. Each filter element in turn contains a sequence of filterRow elements. A filter element has two attributes:

• name. The value is a text string containing the name of the corresponding filter.
• mode. The value is one of the following:
  • DEFAULT. Do nothing.
  • SELECTABLE. Locations and paths are selectable: they will be drawn and their control points will be shown
  • DRAWABLE. Paths will be drawn but their control points will not be shown.
  • INVISIBLE. Paths and locations will not be drawn.

• varname. The value is a text string containing the name of a path or location.
• mode. The mode for the corresponding path or location:
  • DEFAULT. Do nothing.
  • SELECTABLE. The corresponding path or location is selectable: it will be drawn and its control points will be shown.
  • DRAWABLE. The corresponding path will be drawn but its control points will not be shown.
  • INVISIBLE. The corresponding path or location will not be drawn.

The offsets element

The offsets element does not have any attributes. It contains two other elements: an optional basemap element followed by an optional pathmap element. These two elements also do not have any attributes, and if neither is present, the offsets element is not needed. If there is a pathmap element, it must be preceded by a basemap element.

The basemap element contains a sequence of basemapEntry elements and does not contain any other elements. The attributes for the basemapEntry element are

• base. This field provides a string naming the base or reference path for an offset path.
• mindex. An integer code indicating how an offset path is to be generated. These codes are
  • 0. The generated path is a closed path with its distances from the reference path specified by dist1 and dist2.
  • 1. The generated path is an open path on the counterclockwise side of the reference path with its distance from the reference path specified by dist3. The corresponding tangent vectors are parallel to each other.
  • 2. The generated path is an open path on the counterclockwise side of the reference path with its distance from the reference path specified by dist3. The corresponding tangent vectors are antiparallel to each other.
  • 3. The generated path is an open path on the clockwise side of the reference path with its distance from the reference path specified by dist3. The corresponding tangent vectors are parallel to each other.
  • 4. The generated path is an open path on the clockwise side of the reference path with its distance from the reference path specified by dist3. The corresponding tangent vectors are antiparallel to each other.
  In all cases, clockwise and counterclockwise indicate that a point on the generated path is on the left or right side of the corresponding point on the reference path respectively, measured from the direction of the tangent vector at that point.
• dist1. The distance from the reference path in the counterclockwise direction to an offset curve that contains segments on both sides of the reference path.
• dist2. The distance from the reference path in the clockwise direction to an offset curve that contains segments on both sides of the reference path.
• dist3. The distance from the reference path to a single offset path.
• uindex1. A code providing the units for the dist1 attribute (see below for a description of these codes).
• uindex2. A code providing the units for the dist2 attribute (see below for a description of these codes).
• uindex3. A code providing the units for the dist3 attribute (see below for a description of these codes).

• 0. Distances are in custom units.
• 1. Distances are in nanometers (nm).
• 2. Distances are in micrometers (um).
• 3 Distances are in millimeters (mm).
• 4. Distances are in centimeters (cm).
• 5. Distances are in meters (m).
• 6. Distances are in kilometers (km).
• 7. Distances are in inches.
• 8. Distances are in feet.
• 9. Distances are in yards
• 10. Distances are in miles.

The pathmap element contains a sequence of pathmapEntry elements and does not contain any other elements. The attributes for the basemapEntry element are

• path. This attribute contains the name of an offset path.
• base. This attribute contains name of the base or reference path associated with the offset path.

The saved-configuration-file format

• The media type is application/vnd.bzdev.epts-config+zip.
• The ZIP-file entry inputfile contains an XML-encoded String providing a file name.
• The ZIP-file entry imageFlag contains an XML-encoded Booleanindicating if EPTS should be started using an --image argument.
• The ZIP-file entry animation contains an XML-encoded String giving the name of the scripting-language variable whose value will be an instance of org.bzdev.anim2d.Animation after scripts are run.
• The ZIP-file entry scriptingLang contains an XML-encoded String providing the name of the scripting language in use, with the name (DEFAULT) used to indicate the default language.
• The ZIP-file entry joptions contains an XML-encoded object that is equal to the value returned by the getDataVector method of DefaultTableModel for a table containing options for the command java.
• The ZIP-file entry codebase contains an XML-encoded object that is equal to the value returned by the getDataVector method of DefaultTableModel for a table containing additional codebases that will be placed on the module path.
• The ZIP-file entry modules contains an XML-encoded object that is equal to the value returned by the getDataVector method of DefaultTableModel for a table containing the names of additional modules.
• The ZIP-file entry classpath contains an XML-encoded object that is equal to the value returned by the getDataVector method of DefaultTableModel for a table containing additional codebases that will be placed on the class path.
• The ZIP-file entry scripts contains an XML-encoded object that is equal to the value returned by the getDataVector method of DefaultTableModel for a table containing the path names or URLS for scripts that should be executed.
• The ZIP-file entry variables contains an XML-encoded object that is equal to the value returned by the getDataVector method of DefaultTableModel for a table specifying variables and their values. Each row of this table consists of four columns:
  • The first column provides the variables' names.
  • The second column provides the variables' types.
  • The third column provides the variables' values.
  • The fourth column provides the variables' units, which are meaningful for real-valued variables and not other types.
  The second and fourth columns' values are encoded as integers providing the index the instances of JComboBox used to edit their values.

The template-processing-file format

• the media type is application/vnd.bzdev.epts-template-config+zip.
• The ZIP-file entry basicData contains an XML-encoded TemplateSetup.BasicData object. The inner class BasicData is defined as follows:

  
  public static class BasicData {
      public int templateTypeInd = -1;
      public boolean useBuiltins = false;
      public String template = null;
      public String savedState = null;
      public String mapName = null;
  }
  

  The field templateTypeInd sets the selected index of a javax.swing.JComboBox whose values are "SVG", "Table Template", or "PI Template". The field useBuiltins sets the state of a check box indicating if a "choose" button should pick a builtin template or a template stored in an external file. The Strings template, savedState, and mapName are the names of the files or URLs provided by the --template option, the first file-name argument, of the --map option respectively.
• The ZIP file entry tdefTable contains an XML-encoded java.util.Vector, each of whose elements are instances of java.util.Vector with three elements, all instances of java.lang.String. Of these three elements, the first names an iterative directive with a single iteration, the second names a directive that will be defined, and the third provides a value for that directive. Each of these is used to generate a --tdef option. If the iterative directive is TEST, the directive is VAR, and the value is VAL, then
  • If TEST, VAR, and VAL are not empty strings, the corresponding --tdef option is --tdef TEST:VAR=VAL
  • If TEST is empty but VAR and VAL are not empty strings, the corresponding --tdef option is --tdef VAR=VAL
  • If TEST is not empty but VAR and VAL are empty the corresponding --tdef option is --tdef TEST.
  Other combinations are ignored.
• The ZIP-file entry pathmap contains an XML-encoded TemplateSetup.PathMap object. The inner class PathMap is defined as follows:

  
  public static class PathMap extends
      LinkedHashMap<String,Vector<String>>
  {
      public PathMap() {super();}
  }
  

  This table is used to generate --tname and --pname options for the case in which a path is defined as a concatenation of paths in the EPTS table. The key is the name of the new path and the corresponding value is a java.util.Vector whose type parameter is String and whose elements are the names of the path to concatenate.
• The ZIP-file entry globalData contains an XML-encoded TemplateSetup.GlobalData object. The inner class GlobalData is defined as follows:

  
  public static class GlobalData {
      public boolean usesTableTemplate;
      // Table Template options
      public String packageName;
      public String className;
      public boolean isPublic;
      // Path-Iterator Template (--pname) options
      public FlatnessMode fmode = FlatnessMode.NORMAL;
      public double flatness;
      public int limit = 10;
      public boolean gcs;
  }
  

  The field usesTableTemplate is true if options for table templates should be generated and false if options for path templates should be generated. The field packageName is the argument for a --package option; the field --className is the argument for a --class option; the field flatness is the argument for a --flatness option; and the field limit is the argument fora --limit option. When the field isPublic has the value true, a --public option may be generated, and when the field gcs has the value true, a --gcs option may be generated. Finally, the field fmode can have the values TemplateSetup.FlatnessMode.NORMAL, TemplateSetup.FlatnessMode.STRAIGHT, or TemplateSetup.FlatnessMode.ELEVATED, with the last two implying the options --straight and --elevate respectively.
• The ZIP-file entry pathLocMap contains an XML-encoded TemplateSetup.PathLocMap object. The inner class PathLocMap is defined as follows:

  
  public static class PathLocMap
      extends TreeMap<String,PathLocInfo>
  {
      public PathLocMap() {super();}
  }
  

  where the inner class TemplateSetup.PathLocInfo is defined by

  
  public static class PathLocInfo {
      public boolean isPath;
      public boolean active = false;
      public double strokeWidth = 1.0;
      public boolean strokeGCS = false;
      public boolean draw = false;
      public Color drawColor = Color.BLACK;
      public boolean fill = false;
      public Color fillColor = Color.BLACK;
      public int capIndex = 0;
      public double dashIncr = 10.0;
      public String dashPattern = "-";
      public double dashPhase = 0.0;
      public int joinIndex = 0;
      public double miterLimit = 10.0;
      public int windingRuleInd = 0;
      public long zorder = 0;
  
      public PathLocInfo() {isPath = false;}
  
      public PathLocInfo(boolean isPath) {
          this.isPath = isPath;
      }
  

  This table sets parameters associated with paths and locations, including paths that are defined in the PathMap table. The entries are ignored if the fields isPath and active are both false. The field strokeWdith determines the value of the --stroke-width option; the field strokeGCS determines the value of the --stroke-gcs-mode option; the field drawColor determines the value of the --stroke-color option; the field fillColor determines the value of the --fill-color option; the field capIndex determines the value of the --stroke-cap option; the field dashIncr determines the value of the --stroke-dash-incr option; the field dashIncr determines the value of the --stroke-dash-incr option; the field dashPattern determines the value of the --stroke-dash-pattern option; the field dashPhase determines the value of the --stroke-dash-phase option; the field joinIndex determines the value of the --stroke-join option; the field windingRuleInd determines the value of the --winding-rule option; and the field zorder determines the value of the --zorder option. The field --draw must have a value of true for stroke-related options to be used. Similarly the field --fill must have the value true for the fill-color option to be used. The values of the field capIndex indicate a value from the sequence butt, round, and square, with 0 indicating the first, 1 indicating the second, and 2 representing the last of this sequence. Finally, the values of the field joinIndex indicate a value from the sequence bevel, miter, and round, with 0 indicating the first, 1 indicating the second, and 2 representing the last of this sequence.
• The ZIP-file entry outfile contains an XML-encoded String giving an output-file name (an empty string if there is no output file specified), and may be overridden by a command-line option.

Additional documentation

• /usr/share/doc/libbzdev-doc/api/index.html. The web page for the API documentation for the BZDev class library. A link on this page provides a description of the ESP scripting language.
• /usr/share/doc/libbzdev-doc/factories-api/index.html. The web page for the BZDev class library's factories and their parameters. This is usually sufficient for determining how to to configure a factory.
• An Introduction to the BZDev Java Class Library (to be published)
• The ESP scripting language and its use with factory classes. (to be published)
• Programming BZDev Named-Objects and their Factories. (to be published)