2.3. Placement in Anableps¶
From the point of view of the interpreter, any change or initial setting of an object requested by the user, is under the risk of not being consistent (or possible at all) or needing difficult calculations on the side of the interpreter to find the real position. Consider the following examples:
pyramid a: .sides 5 : .base points (1,2,1) (1,2,3) (2,2,3)
a: .height 45cm : .mate top c.bottom : .mate base ground
In the case of the first command for pyramid a, the initial parameters are inconsistent. There can not be a 5-sided pyramid (we are assuming here a regular pentagon) and a base with the given three points. In the second, the two mating constraints can be inconsistent with a height of 45 cm
Furthermore, consider this other valid example:
curve g: ... # a_complicated_curve_I_just_defined
cube c: .tangent g : .parallel north scene.xy_plane
For the cube c, it could be possible to place it tangent to the curve, but the analytical computation is complex or even impossible and there may be more than one solution (even an infinite number of them)
That’s why Anableps takes an heuristical approach to setting and placing objects. For any operation on an object, an iterative algorithm based on ellastic energy (springs) and its minimization is run, until it converges to a solution, or fails (more about kinds of failures, later).
Anablep’s heuristic algorithm is based on forces upon parts of objects. The user specifies constraints, and the algorithm moves things around, trying to fulfill them.
This being said, there are several characteristics of placement that apply both to 2D and 3D. They will be reviewed first. Later, particular details of each mode will be explained:
Placement algorithms uses constraints that exert forces on points, lines and planes. As those points (lines, planes) belong to some object, they, in turn, will force the object rotate, move, or change in several ways. Other constraints are abstract and change quantities. Forces propagate upwards through all the nodes of the tree until some object does not cause further movement upstream.
The process is repeated until the constraints are completely relaxed (that means that the elastic energy stored goes below a preset limit) or a maximum number of iterations is reached and an error is signaled.
2.3.1. simple setting objects is heuristic and iterative too¶
In this way, absolute changes do not exist for any object. Any setting of a property must be sanctioned by the object as a whole (or one of the parents of which the object is a component) to actually taken over. Some sentence like this:
a.side 3cm # this is absolute side is set to 3 cm.
Goes through the same loop of constraint relaxation, only that for this simple setting, it takes only an iteration to converge to the solution.
If, however, several changes are defined in paralel:
a: .side 3cm : .material wood : .left @tangent c.top : .top @angle(30deg) d.bottom
Then several steps are necessary and the enrgy could not become 0 at all.
2.3.1.1. @ operator¶
Note that the @ notation is an alternative for binary operators. In the following example, both arguments are equivalent
: object1 @operator object2 : .operator object1 object2
2.3.2. Place operations¶
In order for the user to tell apart object configuration and object(s) placing, a place operation is provided. The operation moves around and rotates objects until they mate as required.
The place operator has some parameters that enable/disable some transformations:
| .scaling: | on/off. allows or forbids object scaling. User can impose impose a different elastic constant for scaling through the parameter energy (.scaling.energy 2.1) |
|---|---|
| .rotation: | on/off. Allow for rotation. As for scaling, user can impose a penalty (.rotation.energy 2.0) |
| .skew: | Allow for skew on placement. |
As some combination of these are most practical and very often used, place comes with several companion functions that have the right switching on/off by default:
| transform: | just like place but enabling //scaling//, //rotation// and //skew// |
|---|---|
| adjust: | as place but allows xxx and xxx |
| shift: | only allows shifting |
For other combinations the parameters must be set individually.
(tabla con las posibilidades)
2.3.3. Constraints¶
Both setting an object and place operator take constraints. This is not usually
rectangle a: .height 23cm : .width 23cm
This looks like and assignment, but actually, set constraints are being used. In a place operation, constraints are explicitly listed:
place a: .mate east b.west
place a: .at east b.west
place a: .east @at b.west
In the previous example, both syntaxes are equivalent
There are several kinds of constraints that can be used:
| .distance: | sets a distance between two objects. it accepts the additional parameters of ..angle, to impose an angle, too. It does not care about normals being parallel or not. if requires use the parameter place: .antidistance a.top b.bottom |
|---|---|
| .tangent: | it can be specify |
| .mate: | gets two points, liner or planes together. Mate is available under a second name |
| .angle: | angle constraint |
Examples:
a: .side 3cm : .distance 3cm a.bottom c.top :
place: .equal a.side (b.side + 3) : a.color red : a.color Color(10,10,{asdf})
In a setting operation, certain place constraints can be used. See the following examples:
cube a: .side 4cm : .distance top c.bottom 3cm : .mate center d.center ..angle 12deg :
cube a: .side 3cm : .mate center d.center : .center.x @tangent d.top
dube a: .tangent top d.top : .distance 2cm bottom d.bottom ..angle 45deg :
place::
: a.scaling on
: .distance a.top c.bottom 3cm ..strength 3 ..unsolvable ..display_as spring
Constraints are listed in detail in the following paragraphs, as their 2D and 3D versions are a little different.
2.3.4. Tuning the algorithm¶
A setting/place operations finishes when:
- The total elastic energy goes below a threshold
- the maximum number of iterations is reached
- The total elastic energy is not decreasing monotonically.
This exposes the fact that the algorithm works by placing springs on parts of the objects and shrinking them progressively until no tension remains in them.
As we have seen previously, the user can set the relative force for constraints. This is however not normally used unless it’s wanted that some springs will stay stretched:
example
2.3.5. Constraints in 2 dimensions¶
2.3.5.2. tangent¶
Sets a line/plane tangent to other.
2.3.5.2.1. Parameters¶
| distance: | allows putting an additional distance |
|---|---|
| normal: | In a tangent operation, normals to the curve/line/plane can be parallel or anti-parallel. Usually, this is not taken into account. If normal is given a value negative or positive? |
2.3.5.3. Angle¶
Imposes an angle between two entities. Note that not all combinations are possible.
| line-line: | |
|---|---|
| point-point: | not possible |
| plane-plane: | operation is carried away on plane normals |
| line-plane: | |
| point-line: | not possible |
| point-plane: | not possible |
2.3.5.4. mate (at)¶
Brings together two points or two lines. For lines, they can still slide one past the other. All combination are possible
| point-point: | |
|---|---|
| line-line: | |
| plane-plane: | |
| point-line: | |
| point-plane: | |
| line-plane: |
2.3.5.5. set¶
sets force a parameter to get one value. In case there are conflicting
a: .height 25cm : .height 27cm
Error? average?
2.3.6. Place Algorithm, version 3 (Jul22)¶
- OPTIONAL make a backup of original values, so if the placement fails, we can go to state 1
- Repeat this :
2.1) Set all the constraints making proposals (called here gammas, from “goal”)
2.1) Call solve() for the topmost object(s). They go in a depth-first tree traversal. Each object call solve() on its children and THEN sets its children core directly, if something doesn’t fit. This is because parents imposes hard conditions on children
…Until one of these three conditions happen:
- Total constraint energy goes to 0
- Total constraint energy does not decrease monotonically
- Max number of iterations reached
Total constraint energy is the sum of the elastic energy remaining for the constraints applied to the objects. For a placement to succeed, the energy should go to zero. Note that some constraints can be set as “unsolvable”, meaning that we know that they are going to stay with some energy, but this is ok. Those constrains do not take part in the criterium for loop ending (but they do contribute to the sum for the total energy calculations)