Orbit Traps Overview
Orbit Traps are Fractal Science Kit fractal generator programs that define a set of geometric objects located on the complex plane and that keep statistics related to how close the orbit points come to these objects. These statistics are available to the controllers to color the fractal. Orbit Traps are displayed within the context of Mandelbrot Fractals. Note the term Orbit Trap is used for both the program that defines the geometric objects and the objects themselves, depending on context.
See also:
- Mandelbrot Fractal Overview
- Data Collection Programs
- Orbit Trap Map
- Properties Window
- Program Editors
- Fractal Programs
- Program Instructions
- Programming Language
Each program is composed of a set of properties and instructions.
Comments
Always remember to click the Toggle Code View toolbar button at the top of the Program Editor and read the comments given in the comment section of the program's instructions. The comment section contains usage instructions, hints, notes, documentation, and other important information that will help you understand how best to use the program. Once you are done reading the comments, click the Toggle Code View toolbar button again to view the program's properties.
Properties
The following properties are supported:
-
Add Trans Array is a checkbox that can be checked to add a Transformation Array editor as one of the program's properties pages. Users can add 1 or more transformations to the editor and your program can access the transformations using the Transformation Functions.
-
Force Execution is a checkbox that can be checked to force execution of the instructions. If Force Execution is unchecked, the instructions will execute only if required based on what changes were made to the fractal's properties since the last time the instructions ran. This is rarely checked.
Instructions
The remainder of this page can be ignored if you are not a programmer.
At the bottom of the window is an editor pane named Instructions. The editor pane is a simple text editor to view/edit your Program Instructions. See Editing Text for details.
The instructions are divided into sections. Within each section are statements that conform to the Programming Language syntax.
In addition to the Standard Sections, Orbit Traps support 1 other section:
trap:
The trap section is responsible for setting trappedPoint based on how close z comes to the orbit trap. trappedPoint is a TrappedPointInfo object defined as:
Object TrappedPointInfo {
Value
Angle
Index
Delta
}
Value is a measure of how close a point is to the trap. There are 2 basic types of traps: curves and solids. Curves include lines, circles, polygons, ellipses, etc. Solids include disks (the interior of a circle), filled polygons, solid shapes, etc. When you evaluate how close a point is to a trap, you need to consider which type of trap it is. For curves, the Value is the signed scaled distance of the point z to the closest point on the curve. The sign represents which side of the curve z is on. For example, a circle trap would return negative values along the inside edge of the curve and positive values along the outside edge of the curve. When you compute the scaled distance to the curve, you use both the actual distance and the curve width. The scaled distance is given as a percent of the curve width where the curve width is defined as the extent of the trap on either side of the curve. Values between -1 and 1 are trapped. Values less than -1 or greater than 1 are not trapped. Values equal to -1 or 1 are on the inside/outside edge of the trap.
For solid traps, Value is the scaled distance of the point z to the center of the solid. The scaled distance is given as a percent of the distance from the trap center to the exterior of the trap. Values between 0 and 1 are trapped. Values greater than 1 are not trapped. Values are always positive. This is also known as the level set value of the shape. In truth, the center of the solid can be a line or curve and Value is the scaled distance to the closest point on the curve. In this case the distinction between curves and solids is blurred.
Angle is the angle in radians between a horizontal line through the center of the trap and a vector from the center to z. Alternate definitions of the angle are possible. For closed curves you can define the Angle at z as the percent of the curve's path (scaled to 2*Math.PI) that must be traversed to arrive at the closest point on the curve to z. Traps composed of multiple curves/shapes can define the Angle relative to the center of each component shape rather than the center of the entire set. Traps can provide options to control which definition to use.
Index and Delta are small integers between 0 and 32767 used by traps composed of several parts to identify each part or to convey other (discrete) information to the controller. Index and Delta are optional.
Example:
comment:
Implements a circle orbit trap.
trap:
p = ComplexToPolar(z-Center)
trappedPoint.Value = (p.r-Radius) / LineWidth
trappedPoint.Angle = p.a
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).
An alternate implementation is to use the built-in CurveTrap methods as shown below:
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
}
CurveTrap includes methods to add circles, lines, segments, shapes, polygons, and arbitrary curves. These methods are highly optimized and allow you to define complex traps using relatively little code. See CurveTrap Functions for details.
Example:
comment:
Implements a disk orbit trap.
trap:
p = ComplexToPolar(z-Center)
trappedPoint.Value = p.r/Radius
trappedPoint.Angle = p.a
properties:
option Center {
type = Complex
caption = "Center"
details = "Center of disk"
default = 0
}
option Radius {
type = Float
caption = "Radius"
details = "Radius of disk"
range = (0,)
default = 1
}
These instructions implement a disk (filled circle) orbit trap with options to control the Center and Radius of the disk.
Example:
comment:
Implements a disk orbit trap.
global:
CurveTrap.Initialize(0, 0, 1, False, 1, False, 0)
CurveTrap.AddCircle(Center, Radius, True, 0, 0, 0)
trap:
trappedPoint = CurveTrap.Apply(z)
properties:
option Center {
type = Complex
caption = "Center"
details = "Center of disk"
default = 0
}
option Radius {
type = Float
caption = "Radius"
details = "Radius of disk"
range = (0,)
default = 1
}
This is identical to the previous example but uses the built-in CurveTrap methods.
Example:
comment:
Implements a cross orbit trap. Options are provided
to set the center of the shape, and the angle of
rotation. The LineWidth option controls the extent
of trap on either side of the curve.
trappedPoint.Index identifies each line (0 or 1).
Points on the horizontal axis have Index=0 and
points on the vertical axis have Index=1.
global:
const Complex zRotate = Cis(-DegreeToRadian(Angle))
trap:
z = (z - Center) * zRotate
trappedPoint = TrappedPointInfo( \
z.x*z.y/LineWidth, \
Arg(z), \
IIf(Abs(z.x) > Abs(z.y), 0, 1), \
0 \
)
properties:
option Center {
type = Complex
caption = "Center"
details = "Center of trap"
default = 0
}
option Angle {
type = Float
caption = "Angle"
details = "Angle of rotation"
default = 0
range = [-360,360]
}
option LineWidth {
type = Float
caption = "Line Width"
details = "Extent of trap on either side of curve (> 0)"
range = (0,)
default = 0.01
}
This example implements a trap composed of a pair of lines that form a cross about a center point. The trappedPoint's Value, Angle, and Index are set based on the point z. The Delta is always set to 0.
Unlike the simple examples given here, some of the built-in orbit traps are very powerful. For example, the built-in trap Apollonian Gasket is a stand-alone fractal outside the context of the Mandelbrot framework. In these cases, you would normally set the Min Dwell and Max Dwell to 1 on the Orbit Trap Orbit Generation section of the Mandelbrot / Julia / Newton page, to simply view the base trap, unaltered by the Mandelbrot orbit processing. Of course, you can selectively apply areas of the Mandelbrot processing to the orbit trap to produce highly unusual designs. For example, applying different Complex Transformations to the fractal yields countless variations of the base orbit trap.
Built-in Variables
Several built-in variables are available to your instructions:
- TrappedPointInfo trappedPoint
- z
The built-in variable trappedPoint is used to return the results computed by the program. The value z is the point to trap. For convenience, z can be changed but these changes have no effect outside the context of the specific orbit trap program where the change occurs; i.e., it does not affect the orbit or any future trap processing, it is simply a local variable set to the value of the point to trap before each invocation of the trap section.