Implementation of geometric operators

A geometric operator in its most general form takes some parameters and some geometric objects as input to construct one or more output objects.

Parameters in the above formulation include continuous parameters, like the position of a free point or the angle of a point on a circle, as well as discrete parameters, like choosing one element from a finite set. In the following text, the term “parameters” will usually refer to continuous parameters only.

A geometric element is an instance of a geometric operator. It binds the operator to a set of parameters and specific input elements. A geometric element el can contain several pieces of information:

• A current position. This is often stored in el.homog. Depending elements will use that as input.
• An index el.stateIdx into the state arrays. At the indicated position, the element can store information about its continuous parameters as well as data used to facilitate continuous tracing of discrete choices.
• A parameter el.parameter: We'll have to see whether we still need this.
• A list of arguments, which identify elements on which this one depends.
• Some members describing the initial position of the element.
• Various properties controlling appearance, which are of no relevance here.

A geometric operator has functions which operate on these values. The following sections describe the functions and other properties each of the geometric operators may define.

In the following text, there are some terms which have overlapping meaning in general, but which have very specific meaning in this context, so these terms need to be defined.

• The position of an element is the current position. See the section on kind for where that position is stored and the section on updatePosition for how it is computed. The position is the output of an operation.

• The state of an element is something which is used to provide continuity. This is only relevant for either multi-valued operations or free and semi-free elements. The el.stateIdx is used as an index into the stateIn resp. stateOut arrays to facilitate read-only access to the previous state and write-only access to the newly updated state.

  So the state is a subarray of floating-point numbers which are considered as pairs forming complex numbers. This interpretation is relevant since from time to time, numbers which are almost real will be made exactly real.

• The parameter is used to construct an interpolation path while tracing. Usually this will be a vector or matrix for which a linear interpolation (along a complex detour) can be performed. The parameter can be reconstructed from the state.

kind = ‹string›

A short string describing the kind of object which is the result of this operation. Possible values include:

• P – Point
• L – Line
• S – Segment
• C – Conic (which includes circles)
• *s – set of * (e.g. Ps for several points)
• Tr – Transformation

The objects of kind point, line and segment store their result in el.homog. Segments also contain el.startpos, el.endpos and el.farpoint, but this may change. Conics are described by el.matrix, as are transformations. Sets of objects are represented in el.results.

signature = [‹strings›]

While this is not implemented yet, there should be a future version where this property is used to describe the number and types of permissible input elements.

isMovable = ‹boolean›

A boolean property which defaults to false. If set to true, then the element in question is at least semi-free, so it is described by at least one continuous parameter. Elements of this kind may be moved through user interaction or scripts.

stateSize = ‹integer›

A numeric property which defaults to zero. This is the number of floating point numbers which are reserved in the state arrays for each element which is an instance of this operator. So the range of permissible state variables is from el.stateIdx to el.stateIdx + op.stateSize exclusive. Since the state is at times interpreted as an array of complex numbers, this state size should usually be an even number equal to twice the number of complex variables which describe the state.

initialize(el)

This function, if present, will get called exactly once for every element, when the element is first included into the geometric configuration. It may compute the initial parameter of the element from arbitrary properties of the object that describes the element. By the time this function is executed, all previous elements will be initialized and have updated their position.

The initialize function may write to the output state. Any state it writes will be available in the input state when the updatePosition function is run for the first time. The global flag tracingInitial will be true at the time initialize is called. If it does write to the state array, then it might want to set that flag to false so that the initial run of updatePosition already uses tracing to match results, as opposed to simply returning results in an arbitrary order.

getParamForInput(el, pos, type)

Provided with the desired new position (either from mouse input or some assignment in some script) this function computes the corresponding parameter vector to represent either that position or the (in some sense) closest condition under the constraints of a semi-free element. The returned parameter can be used as the end point of some interpolation path. The computation may take the current position of input elements into account.

The type field can be used to describe the kind of input we are dealing with. type === "mouse" represents user interaction, while type === "homog" describes scripted access to the "homog" field of the element. Other types can be introduced as needed, but efforts should be made to keep the number of distinct cases low. For example, there should be no "xy" type, since setting cartesian coordinates can be modeled by setting homogeneous ones.

When the input is "mouse", then the position represents the current mouse position, expressed as homogeneous coordinates, and already including an offset to the original point position which was remembered from the mouse down.

getParamFromState(el)

Reading from the current input state stateIn, this function returns the parameter corresponding to that state. The returned parameter can be used as the starting point of some interpolation path. The returned result should not depend on the current position of any input element.

putParamToState(el, param)

Write a given parameter value to the state stateOut. This function is called along ain interpolation path, to adjust the position of the element which is being moved.

parameterPath(el, tr, tc, src, dst)

Compute parameter along interpolation path. If absent, a default implementation will be used, which performs a single semi-circular complex detour. tr is the real parameter, in the range -1…1. tc is a resulting complex parameter on the seimicircle. Either tr or tc may be used to compute the alternate path. src and dst are the parameters at the endpoints of the path. The returned value should be a linear interpolation between these.

updatePosition(el, isMover)

Every geometric operator must implement this function. It will recompute the position of the resulting element based on the argument elements and the current parameters.

For elements which have state, updatePosition should write all of the state variables, usually after taking the previous state into account. Even if the new state should be identical to the old one, that should be made explicit by copying the values.

The isMover argument will be true if the current element is the one which is actively being moved around, and false if it is only updated in response to one of its arguments changing position.