CurveTrap Functions Support
The Fractal Science Kit fractal generator CurveTrap functions are supported only in the Orbit Trap instructions. Each set of instructions has access to a single CurveTrap object that you can use to implement your trap. The CurveTrap object maintains a set of curves that are combined to form the trap. You should call CurveTrap.Initialize before you call any of the other methods. Next you should call 1 or more of the CurveTrap.Add... methods to add different curves to the set. The calls to CurveTrap.Initialize and each of the CurveTrap.Add... methods should be placed in the global section of your instructions. Finally, in the trap section of your instructions, you should call CurveTrap.Apply to calculate the trap's required TrappedPointInfo. The CurveTrap functions are highly optimized and can dramatically speed up your program. However, performance will suffer if you add a large number of curves to the trap (> 2500) .
Example:
global:
CurveTrap.Initialize(...)
CurveTrap.Add...(...)
CurveTrap.Add...(...)
CurveTrap.Add...(...)
trap:
trappedPoint = CurveTrap.Apply(z)
This example shows the typical pattern used to implement a trap using the CurveTrap methods.
Example:
comment:
Implements a circle orbit trap.
global:
CurveTrap.Initialize(0, 0, 1, False, 1, False, LineWidth)
CurveTrap.AddCircle(Center, Radius, False, 0, 0, 0)
trap:
trappedPoint = CurveTrap.Apply(z)
properties:
option Center {
type = Complex
caption = "Center"
details = "Center of circle"
default = 0
}
option Radius {
type = Float
caption = "Radius"
details = "Radius of circle"
range = (0,)
default = 1
}
option LineWidth {
type = Float
caption = "Line Width"
details = "Extent of trap on either side of curve"
range = (0,)
default = 0.1
}
These instructions implement a simple circle orbit trap with options to control the Center and Radius of the circle and the width of the line on either side of the curve (LineWidth).
The built-in Orbit Traps include many examples of using these methods.
CurveTrap.Initialize
void CurveTrap.Initialize(
center,
angle,
scale,
alternateAngle,
cycleLength,
scaleTrapValue,
lineWidth
)
CurveTrap.SetCurveOverlap(overlap)
CurveTrap.InitializeSolidPolygonOptions(minimumValue, power)
CurveTrap.Initialize initializes the CurveTrap object based on the given arguments. The center, angle, and scale, set the center point, angle of inclination, and scale factor for the entire set of curves.
The Boolean argument alternateAngle controls the algorithm used to calculate the trapped point angle. Normally, the angle of each trapped point is the angle of the point relative to the trap's center. However, if alternateAngle is true, the method used to compute the angle depends on the type of curve. For shapes, the alternate angle is relative to each shape's center rather than the center of the entire trap. For all other curves, the alternate angle is based on how far along the curve's path the point is; i.e., the angle ranges from 0 to 2*Math.PI as the point traverses along the path of the curve. In other words, if alternateAngle is true, the angle is relative to each of the trap's individual curves rather than relative to the entire set. You will normally want to set alternateAngle to true when you are using the trap with a controller that maps a texture or pattern onto the surface of the trap, unless you are using a planar projection, in which case you should set alternateAngle to false.
The cycleLength argument is used only for lines and only if alternateAngle is true. It is the distance along the line that maps to 2*Math.PI when computing the trapped point angle. The scaleTrapValue argument is a Boolean value that, when true, instructs the CurveTrap to scale trap values proportional to how far the trapped point is from the origin. This makes lines get wider as they move away from the origin and narrower as the move closer to the origin. The lineWidth argument controls the extent of non-solid traps on either side of the curve.
Typically, you will provide options in your trap's properties section to allow the user to control 1 or more of these settings and call CurveTrap.Initialize with the user's selections.
CurveTrap.SetCurveOverlap sets the state variable overlap used to determine how intersections are handled on self-intersecting curves. If overlap is True, the curve passes over or under (overlaps) itself, thus avoiding the intersection. If overlap is False, the curve intersection is handled by blending the curves together at the point of intersection.
CurveTrap.InitializeSolidPolygonOptions is used to initialize options associated with solid polygons. It should be called after CurveTrap.Initialize and is not required unless you plan to add solid polygons to the set of traps (see CurveTrap.AddSolidPolygon below). minimumValue is the smallest value returned by solid polygon traps and power is the power applied to the value. If CurveTrap.InitializeSolidPolygonOptions is not called, minimumValue is 0 and power is 1.
CurveTrap.Add... Common Arguments
All of the CurveTrap.Add... methods share 3 arguments: level, index, and delta. The level argument is rarely set to a value other than 0, but can be used to force selected curves above other curves by setting their level higher. That is, all curves of level 0 will be displayed below curves of level 1, and they in turn will be below curves of level 2, etc. If all the levels are 0, all the curves will be blended into a single level. Setting level to a value other than 0 is less efficient than setting all levels to 0.
The index argument can be used to assign each curve a different index value which can be mapped to the trap index value and accessed by the controller and used to color the trap. Set the Trap Index Map to Trap Index on the Orbit Trap Map properties page if you need to access the assigned index value in your controller. index should be an integer between 0 and 32767.
The delta argument can be used to assign each curve a different delta value which can be mapped to the trap delta value and accessed by the controller and used to color the trap. Set the Trap Delta Map to Trap Delta on the Orbit Trap Map properties page if you need to access the assigned delta value in your controller. delta should be an integer between 0 and 32767.
If any of these values are not required for your trap, simply pass 0 for the associated argument.
CurveTrap.AddCurve
void CurveTrap.AddCurve(
points[],
count,
closed,
cornerStyle,
scale,
angle,
shift,
level,
index,
delta
)
void CurveTrap.AddCurve2(
points[],
count,
closed,
cornerStyle,
lineWidth,
scale,
angle,
shift,
level,
index,
delta
)
CurveTrap.AddCurve adds a curve (set of line segments) through the count points in the points[] array. If the Boolean argument closed is true, the last point is connected to the first. Otherwise the curve is left open.
The arguments scale, angle, and shift, apply a scaling, rotation, and translation to the curve points relative to the origin.
The cornerStyle argument is one of the values from the CornerStyles enum and defines the style applied to each point. You should use the value CornerStyles.Round unless the number of points is small. cornerStyle is ignored and the curve displayed with CornerStyles.Round if the curve is open.
The CornerStyles enum is defined in the built-in macros as:
#define CornerStyles
enum CornerStyles {
Sharp, "Sharp"
Round, "Round"
Hyper, "Hyper"
}
#end
Use the following statement in the properties section to define the enum in your program:
#include CornerStyles
CurveTrap.AddCurve2 is identical to CurveTrap.AddCurve but has the additional lineWidth argument to allow you to use different line widths for the curves you create.
The delta value for curves can be set to the special value -1 which results in using the curve's segment index for Trap Delta.
CurveTrap.AddKnot
void CurveTrap.AddKnot(
points[],
count,
overlay[],
overlayCount,
cornerStyle,
lineWidth,
scale,
angle,
shift,
level
)
CurveTrap.AddKnot adds a set of curves based on the count points in the points[] array. The points in the array define one or more closed curves. The curves are separated by a point equal to the constant NaN. For example, if count is 9 and points[4] equals NaN, the knot would be composed of two curves, each containing 4 points; points[i], i=0 to 3 and points[i], i=5 to 8.
overlay[] is a set of overlayCount special points used to determine which line segment is on top where they cross. Each overlay[] value is a complex number where the X and Y components are integer index values into the points[] array. A value (i,j) indicates the segment from points[i] to points[i+1] is above the segment from points[j] to points[j+1].
The arguments scale, angle, and shift, apply a scaling, rotation, and translation to the curve points relative to the origin.
The cornerStyle argument is one of the values from the CornerStyles enum and defines the style applied to each point.
lineWidth is the line width for the curves.
The CornerStyles enum is defined in the built-in macros as:
#define CornerStyles
enum CornerStyles {
Sharp, "Sharp"
Round, "Round"
Hyper, "Hyper"
}
#end
Use the following statement in the properties section to define the enum in your program:
#include CornerStyles
The resulting trap uses the curve index for Trap Index and the curve's segment index for Trap Delta.
CurveTrap.AddSolidPolygon
void CurveTrap.AddSolidPolygon(
points[],
count,
border,
scale,
angle,
shift,
level,
index,
delta
)
CurveTrap.AddSolidPolygon defines a solid polygon with vertices given by the count points in the points[] array.
border is a value greater than 0 used to define the size of the border around the outer edge of the polygon. The Trap Value for trapped points that fall inside the border is the minimumValue set in the call to CurveTrap.InitializeSolidPolygonOptions.
The arguments scale, angle, and shift, apply a scaling, rotation, and translation to the curve points relative to the origin.
CurveTrap.AddShape
void CurveTrap.AddShape(
type,
center,
radius,
angle,
solid,
level,
index,
delta
)
void CurveTrap.AddShape2(
type,
center,
radius,
angle,
solid,
lineWidth,
level,
index,
delta
)
CurveTrap.AddShape adds a shape from the ShapeTypes enum. The type argument specifies the shape type. Arguments center, radius, and angle, control the position, size, and inclination of the resulting shape. If solid is true the shape is displayed as a solid figure. Otherwise, the curve outlines the shape.
You can access the list of types by including the following statement in your properties section:
#include ShapeTypes
See Shape Functions for the full list of types defined by ShapeTypes.
CurveTrap.AddShape2 is identical to CurveTrap.AddShape but has the additional lineWidth argument to allow you to use different line widths for the shapes you create.
CurveTrap.AddCircle
void CurveTrap.AddCircle(
center,
radius,
solid,
level,
index,
delta
)
void CurveTrap.AddCircle2(
Circle c,
solid,
level,
index,
delta
)
void CurveTrap.AddCircle3(
center,
radius,
solid,
linewidth,
level,
index,
delta
)
Complex CurveTrap.CircleExists(center, radius)
Complex CurveTrap.CircleExists2(Circle c)
CurveTrap.AddCircle adds a circle with the given center and radius. If solid is true the circle is displayed as a solid figure. Otherwise, the curve outlines the circle. CurveTrap.AddCircle2 is identical to CurveTrap.AddCircle but it takes the center and radius from the argument c. CurveTrap.AddCircle3 is identical to CurveTrap.AddCircle but has the additional lineWidth argument to allow you to use different line widths for the circles you create.
CurveTrap.CircleExists returns True if a circle with the given center and radius exists in the set of curve traps already defined. CurveTrap.CircleExists2 is identical to CurveTrap.CircleExists but it takes the center and radius from the argument c.
CurveTrap.AddLine
void CurveTrap.AddLine(
point,
angle,
level,
index,
delta
)
void CurveTrap.AddLine2(
p0,
p1,
level,
index,
delta
)
CurveTrap.AddLine adds a line through point, inclined at angle radians. CurveTrap.AddLine2 adds a line through the points p0 and p1.
CurveTrap.AddSegment
void CurveTrap.AddSegment(
p0,
p1,
level,
index,
delta
)
Complex CurveTrap.SegmentExists(p0, p1)
CurveTrap.AddSegment adds a line segment with endpoints p0 and p1.
CurveTrap.SegmentExists returns True if a segment with the given endpoints p0 and p1 exists in the set of curve traps already defined.
CurveTrap.Apply
TrappedPointInfo CurveTrap.Apply(z)
CurveTrap.Apply applies the set of curves to the point z returning the required TrappedPointInfo.