Orbit Trap Controllers |
|
Orbit Trap Controllers OverviewOrbit Trap Controllers are programs (called controllers hereafter) used by the Fractal Science Kit fractal generator to map sample data collected during the fractal iteration, to colors for display. Each controller is composed of a set of properties and instructions. The properties are in a set of sections at the top of the page and the instructions are at the bottom of the page. To view the instructions, use the editor's Toggle Code View button to hide the properties and expand the instructions to fill the space. As the sample points are processed by the Fractal Science Kit fractal generator, each sample is passed to the (single) Orbit Trap Master Controller who calls 0 or more Orbit Trap Controllers to process the sample. The controller's instructions are responsible for assigning a Color to the special variable color based on selected fields in the sample. The properties include a set of gradients and/or textures that can be accessed within your instructions, as required. You can use sample data to select which gradient/texture to reference, and to index into the selected gradient/texture to obtain a color. Alternatively, you can use sample data to create a color directly. Orbit Trap Controllers have many similarities with Classic Controllers but have several specialized features that make working with orbit trap data much easier. Unlike Classic Controllers, Orbit Trap Controllers are only called if the point is trapped. After the color is returned from your instructions, the controller uses the property settings on this page to further process the color as defined below. See also:
Each program is composed of a set of properties and instructions. CommentsAlways 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. Gradients
The following properties are defined in the Gradients section:
Textures
The following properties are defined in the Textures section:
Properties
The following properties are defined in the Properties section:
Color Space Adjustment
The Color Space Adjustment section is used to adjust individual components of the HSL (Hue/Saturation/Lightness) or HSV (Hue/Saturation/Value) color space. The adjustments are applied to the color returned by your program. To use these settings, you select the color space you want to adjust (HSL or HSV) and then set the values for the individual components associated with the selected color space. The HSL color model supports Hue, Saturation, and Lightness components. The HSV color model supports Hue, Saturation, and Value components. The Hue is identical in both color models but the Saturation is quite different. The Lightness and Value components are unique to the HSL and HSV color models, respectively. See HSL and HSV for details on these color models. The following properties are defined in the Color Space Adjustment section.
Color Adjustment
The Color Adjustment section is used to adjust the brightness, contrast, and gamma of the color returned by your program. The following properties are defined in the Color Adjustment section.
3D MappingThe 3D Mapping section applies 3D shading to the color returned by your program. A data value is mapped to a virtual height and a simple 3D shading model is applied to the image. Properties are provided to control the light intensity, ambient light, and specular reflection. Additional properties control the data/height mapping. The 3D Mapping processing supports 2 different lighting models. The first lighting model maps Sample.TrapValue to a height and assumes a single light source directly above the surface. The second lighting model uses a surface normal vector and 1 or 2 light sources to determine the amount of light that is displayed at a given point. To use the second lighting model, you set the Map To property to Surface Normal or Surface Normal (Restricted).
Map To is the data value mapped to height when performing 3D processing. If Map To is set to Trap Value or Composite Height, the lighting model assumes a single light source directly above the surface. Set Map To to Trap Value to map Sample.TrapValue to height. Set Map To to Composite Height to access the value of compositeHeight, computed by your instructions. It is expected that compositeHeight is set to a value between 0 and 1. By default, a value of 0 maps to a visual high and a value of 1 maps to a visual low. Set Map To to Surface Normal or Surface Normal (Restricted) to use a surface normal vector (Surface Normal (Trap Value)) and 1 or 2 light sources to determine the amount of light that is displayed at a given point. The Surface Normal (Restricted) setting is quick to set up but has far less flexibility than the unrestricted version and many of the 3D Mapping properties are disabled. When using the restricted version, you will probably need to add some ambient light or use 2 light sources to get the best results. When you set Map To, the properties appropriate for the associated lighting model are enabled, and the properties not appropriate for the associated lighting model are disabled. When Map To is set to Surface Normal or Surface Normal (Restricted) a surface normal vector based on the trap value is used for the mapping. Additional control over the surface normal computation is found in the Surface Normal (Trap Value) section of the Orbit Trap page. Secondary Light Blend is used to define a second light source for the surface normal lighting model, and to set the blending function used to blend the 2 light sources together. There are quite a few blending functions, and you can experiment with the different settings to see which one produces the best results in a given situation. If Secondary Light Blend is None, a single light source is used. Light Angle 1, Light Elevation 1, and Light Intensity 1, define the angle, elevation, and intensity of the first light source. Light Angle 2, Light Elevation 2, and Light Intensity 2, define the angle, elevation, and intensity of the second light source. The light angle is given as an angle (in degrees between -360 to 360) relative to the X axis. The light elevation is given as an angle (in degrees between -360 to 360) relative to horizontal. Normally, the elevation is between -60 and 60 but this is not required. The light intensity is an integer between 0 and 255 that represents the intensity of the light source. A value of 0 is void of light and a value of 255 is full intensity. This value is normally between 200 and 240. Ambient Light is an integer between 0 and 255 that represents light that reaches the object reflected off other objects. A value of 0 includes no ambient light. This value is normally between 0 and 20. Specular K is a value between 0 and 1 that represents a specular reflection constant. This value is normally between 0.01 and 0.1 where smaller values result in less specular reflection. This property is disabled for the surface normal light model and you should check Apply Highlight below to add highlights to the image. Specular N is an integer greater than 0 that represents a specular reflection exponent. This value is normally between 5 and 100. Use small values for larger, less intense highlights, large values for smaller, more intense highlights. This property is disabled for the surface normal light model and you should check Apply Highlight below to add highlights to the image. Smooth Reflection is a Boolean that, when checked, applies a smoothing function to the specular reflection. This property is disabled for the surface normal light model.
The remainder of the 3D Mapping section contains properties to adjust the lighting model results. Power, Factor, and Offset are applied to the value. value ^= Power When using the surface normal light model, Factor is normally between 0.5 and 2 (or -0.5 and -2) but can fall outside that range on occasion. If you are not using the surface normal light model, Factor should be a small positive integer. The Power, Factor, and Offset adjustments, can result in values outside the range 0 to 1. Each value is mapped to a unit index and wrapped into the range 0 to 1. Check Alternate Peak to alternate the sign of the peak (see Peak below) on odd units. Check Alternate Shadow to alternate the light/dark shadow of edged styles (see Style below) on odd units. This property is disabled for the surface normal light model. Style can be set to Rounded, Edged, Double Edged, or Flattened. Rounded causes the trap to have a rounded appearance as the trap moves away from the trap center. Edged causes the trap to have an edge along the trap center, and appear flat on either side of the edge giving the trap a bar-like appearance. Double Edged causes the trap to have edges on either side of the trap center, and appear flat in the center and on either side of each edge. Flattened is similar to Double Edged but has rounded edges. Normally, when you set Style to Edged, Double Edged, or Fattened, you will set Peak to Constant but the other values look good in some situations. The Edged, Double Edged, and Fattened styles are not compatible with all trap types. Shadow is a value between -1 and 1 that defines the strength of the shadow applied to 1 of the 2 sides of the trap when Style is set to Edged, Double Edged, or Fattened. If Shadow is less than 0, the shadow is applied to the side adjacent to the inside edge. If Shadow is greater than 0, the shadow is applied to the side adjacent to the outside edge. See Trapped Point Value for a discussion of what constitutes an inside/outside edge. The magnitude of Shadow controls how dark the side will appear; i.e., larger magnitudes appear darker. Shadow is disabled unless Style is set to Edged, Double Edged, or Fattened. Shadow Cycles is an integer greater than or equal to 0 that represents the number of cycles applied to the Shadow. If Shadow Cycles is 0, the Shadow value is used for the entire trap. Otherwise, the shadow value oscillates between Shadow and -1*Shadow as the trap angle changes. Shadow Cycles represents the number of oscillations. Corner Width is the width of the corner for the Edged and Double Edged styles. Edge Width is the width of the edge for the Edged, Double Edged, or Fattened styles. Style, Shadow, Shadow Cycles, Corner Width, and Edge Width, are disabled for the surface normal light model. Peak, Peak Arg (S), and Peak Arg (N), control the location and shape of the trap highlights. Peak is one of the following:
Peak Arg (S) and Peak Arg (N), or S and N for short, are used by some of the settings to vary the effect as indicated in the text of the setting. Peak of Center (the default) displays the highlight down the center of the trap. Changing Peak to Constant, moves the highlight toward the inside edge if S<0 or the outside edge if S>0. Wave moves the peak in a sine wave as the trap angle goes from 0 to 360. N is the integer number of cycles in the wave pattern and S is the Amplitude of the wave. The remaining settings generate Wave variations. Invert Value is a Boolean value that, when checked, replaces value with 1-value. Highs become lows and lows become highs. Curvature is used to soften the 3D effect. A value of 1 is maximum curvature and results in the strongest 3D effect. Values greater than 1 increase the radius of curvature and soften the 3D effect. Apply Depth is a Boolean value that, when checked, strengthens the 3D effect by adding depth to the mapped value. In some cases this adds a metallic quality to the resulting colors. You may need to adjust the Depth Power, Depth Factor or the Ambient Light if the resulting image appears too dark. Depth Power defines the shape of the power curve used for depth processing. Depth Factor is the factor applied to the mapped value at maximum depth. Apply Highlight is a Boolean value that, when checked, adds highlights to the image. Normally, you should check Apply Highlight when using the surface normal lighting model, but you can check Apply Highlight to strengthen the highlights even when not using the surface normal lighting model. Highlight Width controls the width of the highlight. Highlight Factor controls the strength of the highlight. Depth Mapping
The Depth Mapping section applies depth shading to the color returned by your program. Sample.TrapDwell is mapped to a virtual depth and a simple depth shading model is applied to the image. Properties are provided to control the power/factor used to define the sample/depth mapping, and to lighten rather than darken the colors as the depth increases. Typically, you would activate the Depth Mapping to darken samples with large dwells to make it appear these points were receding into the distance. Check Highlight Depth to make the points fade to white rather than fade to black. The Depth Mapping is applied only if the Method property on the Orbit Trap properties page is set to Trap First Point. In all other cases, Depth Mapping is ignored. The following properties are defined in the Depth Mapping section.
InstructionsThe 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 Trap Controllers support 1 other section: color: This section is responsible for setting the color for the current sample point. The color is returned in the built-in variable color. Built-in VariablesSeveral built-in variables are available to your instructions:
Controllers can access the above built-in variables. color is used to return the color computed by the program. compositeHeight is used to return a value for the Map To setting in the 3D Mapping section. That is, if the 3D Mapping section's Map To is set to Composite Height, the instructions should set compositeHeight to a value between 0 and 1 for this purpose. Otherwise, compositeHeight need not be set. compositeHeight is rarely used. pixel is the location in the complex plane of the current sample point and is read-only. color is a Color object defined as: Object Color { Each of the fields should be a floating point value between 0 and 1, inclusive. See the Color Functions for details. The Color object supports the RGB, HSL, and HSV color models but the Fractal Science Kit expects color to conform to the RGB color model. If your program generates a color using the HSL or HSV color model, you must convert the color to the RGB color model prior to returning. The color's Alpha value is used to set the color's opacity. A value of 0 makes the color totally transparent and a value of 1 makes the color totally opaque. Values between 0 and 1 can be used to define colors that are translucent. The controller's Opacity Factor and Scale Opacity properties are applied to color's Alpha value set by the instructions. Example: color: This example calls the Gradient Function Gradient.Color to map the normalized trap angle (Sample.TrapAngle) to a color using the 1st gradient in the controller's list of gradients (i.e., gradient 0). Another common method of accessing the sample data is to use a SamplePointValue Option to allow the user to select a field from the Sample object (described below) using the associated property on the Properties Page. Example: color: This example maps a user selected SamplePointValue called Value, to a gradient index thereby obtaining a color. Unlike other option types, a SamplePointValue option does not return a constant, but instead, uses the SamplePointValue setting to access the corresponding component of the current sample which is returned by the option (in this case, Value). In this example, the option's default value is given as Sample.TrapAngle which equates to the previous example if the user does not change it. Example: comment: Like the previous example, this controller maps a user selected SamplePointValue to a gradient index thereby obtaining a color. However, instead of simply using controller 0 as in the previous example, this controller calls the function Gradient.Color(ColorScheme,Value) to map the sample data to a color using the gradient in the controller's list of gradients indexed by ColorScheme. See GradientIndex Options for details. Example: color: This example allows the user to define a ColorSet Option with up to 8 colors (returned in the array Colors[]) and an index map (IndexMap) set to Trap Dwell, Trap Index, or Trap Delta. Based on the index map, the program sets index to either Sample.TrapDwellRaw, Sample.TrapIndexRaw, or Sample.TrapDeltaRaw, and then uses index to access 1 of the colors found in Colors[]. Note the call to WrapIndex to wrap index to a value between 0 and Count-1 inclusive. See the built-in Orbit Trap Controllers for more complex examples that map textures or geometric patterns to the traps. ConstantsThe following constants are available to your instructions:
ViewportMagnification is the current fractal's magnification. The magnification can be viewed by executing the Resize command on the View menu of the Fractal Window. Accessing Sample DataThe data associated with the sample being processed is accessed by the controller using the Sample object. The Sample object is a read-only object that contains all the collected data for the sample point. Many of the fields have been normalized based on normalization settings for the associated field, and the value is between 0 and 1. In some cases both the raw value and the normalized value are available. The following fields are associated with the Sample object for Orbit Trap Controller programs:
Many of the Sample.Trap... values are set by the Orbit Trap instructions when the point is trapped. However, depending on other trap related properties, the Fractal Science Kit may combine several trapped points into a single point saved with the sample. The following discussion is from the perspective of a point trapped by a single trap but you should be aware that this is not always the case and these values may be the result of blending several trapped points into a single point. See Orbit Trap Blend for details. Sample.TrapValue is a measure of how close a point is to the trap. The interpretation of the value depends on whether the trap is a curve or a solid shape. For curves, Sample.TrapValue is the signed distance to the closest point on the trap as a percent of the curve width. The sign indicates on which side of the curve the point lies. For solid shapes, Sample.TrapValue is a level set value given as a percent of the distance from the center of the shape. Sample.TrapValue ranges from -1 to 1 for curves and 0 to 1 for solid shapes. See Trapped Point Value for details. Sample.TrapAngleRaw is the angle (in radians) assigned to the point by the trap. This is usually the angle formed by the vector from the trap center to the point and a horizontal line through the trap center but other definitions are possible. All of the other angle values are normalized to the range 0 to 1. Sample.TrapAngle is a straight linear mapping of the angle where 0 to 360 maps to 0 to 1. Sample.TrapAngleBounce maps angles from 0 to 180 into values from 0 to 1, and maps angles from 180 to 360 into values from 1 to 0. That is, as the angle increases from 0 to 360, Sample.TrapAngleBounce starts at 0, increases to 1 at the half-way point (180), and then decreases (bounces) back to 0. Sample.TrapAngleCos is identical to Sample.TrapAngleBounce except that it uses a cosine based wave rather than a triangle based wave so it is smoother at the extremes. See Trapped Point Angle for details. Sample.TrapDwellRaw is the dwell value of the orbit point that was trapped. Sample.TrapDwell is the normalized dwell value. Sample.TrapIndexRaw and Sample.TrapDeltaRaw are the Index value and Delta value assigned to the point by the trap instructions. Sample.TrapIndex and Sample.TrapDelta are the normalized values. See Trapped Point Index/Delta for details. Sample.TrapCountRaw is the number of traps that trapped the point. Sample.TrapCount is the normalized count. Sample.TrapId is the Trap Id of the orbit point that was trapped. The Trap Id is set on the Orbit Trap Map page. All the remaining fields are described in the Classic Controllers section. However, the following fields are not initialized if the Orbit Opacity On property is checked on the Orbit Trap page:
In addition, if the Orbit Opacity On property is checked, the following fields are not smoothed even if Smooth Angle is checked in the Orbit Generation section of the Mandelbrot / Julia / Newton page:
The reason for these exceptions is that when Orbit Opacity On is checked, the controllers are called during sample generation to process each of the trapped points but these fields are not initialized/smoothed until after sample generation is complete. |
Copyright © 2004-2019 Ross Hilbert |