Orbital Controllers

Home • Gallery • Tutorials • Download • Purchase • Site Map
 

Orbital Controllers Overview

Orbital 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) Orbital Master Controller who calls 0 or more Orbital 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.

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.

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.

Gradients

Fractal Science Kit - Orbital Color Controllers Properties Gradients

The following properties are defined in the Gradients section:

  • Gradients are the ordered list of gradients available to the controller. The Gradient List Control allows you to add/remove gradients to/from the list, reorder the list, cut/copy/paste gradients between lists on other properties pages, undo/redo list changes, edit gradients in the list using the Gradient Editor, and open the Gradient Browser so you can copy/paste existing gradients from the Built-in Gradients or My Gradients into the list. When you paste a gradient into the list, a copy of the gradient is made so that any changes to the gradient will not affect the original. Your program can access this list using the Gradient Functions.

Textures

Fractal Science Kit - Orbital Color Controllers Properties Textures

The following properties are defined in the Textures section:

  • Textures are the ordered list of textures available to the controller. The Texture List Control allows you to add/remove textures to/from the list, reorder the list, cut/copy/paste textures between lists on other properties pages, undo/redo list changes, and repair broken textures. Your program can access the list using the Texture Functions. Each texture in the list is displayed using the name of the associated texture file without the file extension. If a single texture is selected, the texture's image is displayed in the preview area on the right side of the control. If the texture file no longer exists or cannot be loaded, the name will also include the text [error loading file] and a default texture (a white box) is used. You should replace these items or remove them from the list. To replace a broken texture in the list, simply select it and click the Repair toolbar button and select the replacement.

Properties

Fractal Science Kit - Orbital Color Controllers Properties

The following properties are defined in the Properties section:

  • Apply Opacity is used to turn on opacity processing and enable the Opacity Mapping properties (described below). Opacity processing uses data from previous orbit points when generating the current point's color based on the the values of the Opacity Mapping properties. To use only the data from the current orbit point you would uncheck Apply Opacity. Opacity processing is expensive and unchecking Apply Opacity will improve the controller's performance.

  • Blend Colors is used to map the data to color for each orbit point, and then blend the set of colors based on the opacity settings in the Opacity Mapping section (described below). Uncheck Blend Colors to blend the data values for each orbit point based on the opacity settings, and then map the blended data to color.

  • Adjust Depth is used to turn on depth adjustment processing and enable the Depth Adjustment properties (described below). Depth adjustment processing uses the sample field density (Sample.Count) to obtain a depth factor, and scales the color's (HSV) Value based on this factor in conjunction with the Depth Adjustment properties.

  • Adjust Lightness is used to turn on lightness adjustment processing and enable the Lightness Adjustment properties (described below). Lightness adjustment processing uses the sample field density (Sample.Count) to obtain a lightness factor, and scales the color's (HSL) Lightness based on this factor in conjunction with the Lightness Adjustment properties.

  • Depth/Lightness is used to control the method used to blend the depth and lightness adjustments when both Adjust Depth and Adjust Lightness are checked. The possible settings are Density Map - Depth to Lightness, Density Map - Lightness to Depth, or Average Value. The Density Map settings use the sample field density (Sample.Count) as a weight in a linear blend of the colors resulting from the depth and lightness adjustments. The Average Value setting simply averages the 2 colors. This option is disabled unless both Adjust Depth and Adjust Lightness are checked.

  • 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.

Opacity Mapping

Fractal Science Kit - Orbital Color Controllers Properties Opacity Mapping

The Opacity Mapping properties are used to control opacity processing. Opacity processing uses data from previous orbit points when generating the current point's color. The Opacity Mapping properties are combined to form an opacity value that represents the amount of color contributed by each orbit point. For example, if the opacity is fixed at 0.5, then 50% of the color is taken from the current point. Of the remaining space, 50% is filled with the color from the previous orbit point, and so on. The result is that the color is composed of contributions from several orbit points; i.e., 50% from Orbit(N), 25% from Orbit(N-1), 12.5% from Orbit(N-2), etc.

The opacity is based on Map To which can be set to one of the sample fields or the special value <Fixed Value> (the default). If Map To is set to one of the sample fields, the field's value with respect to each orbit point is used as the opacity for that point (modified by Invert Opacity and Opacity Factor as described below). If Map To is set to <Fixed Value>, the opacity is set to the Opacity Factor for all orbit points.

Invert Opacity, if checked, inverts the sample field value before setting opacity. That is, assuming the sample field value is value, we set opacity to 1-value rather than value. Invert Opacity is disabled if Map To is set to <Fixed Value>.

Opacity Factor is used as the opacity if Map To is set to <Fixed Value>. If Map To is set to one of the sample fields, the opacity is multiplied by Opacity Factor.

Attractor Opacity is used to adjust the opacity based on the value of Sample.AttractorIndexRaw. Click the Adjust Attractor Opacity button to display the Adjust Attractor Opacity dialog.

Fractal Science Kit - Orbital Color Controllers Properties Adjust Attractor Opacity

Set Count to the total number of attractors and type ENTER and Count fields will be displayed to let you set the adjustment for each attractor index value. The adjustment should be given as a percent increase (0 to 100) or percent decrease (-1 to -100) and the opacity value for the given attractor will be adjusted up or down by that amount. The example above increases the opacity for attractor 0 by 100% of the space remaining in the color, and decreases the opacity for attractor 1 by 90%. The opacity value for all other attractors is unchanged. These adjustments are useful when working with IFS fractals where one or more of the attractors have very high weights. Using this dialog, you can decrease the opacity for the dominant attractors so the attractors with smaller weights can contribute to the color of the point.

Finally, the opacity is multiplied by the the Alpha value of the color returned by your instructions. For greater control over the opacity setting, set Map To to <Fixed Value> and Opacity Factor to 1. Then opacity is set to the Alpha value of the color returned by your instructions.

The following pseudo-code details how opacity is set for each orbit point:

if (MapTo is <Fixed Value>) {
  opacity = OpacityFactor
} else {
  opacity = the MapTo sample field value
 
  if (InvertOpacity) {
    opacity = 1 - opacity
  }
  opacity *= OpacityFactor
}
opacity = opacity modified by the Adjust Attractor Opacity settings
opacity *= color.Alpha

Depth Adjustment

Fractal Science Kit - Orbital Color Controllers Properties Depth Adjustment

The Depth Adjustment section adjusts the (HSV) Value of the color returned by your program. The sample field density (Sample.Count) is mapped to a depth factor. Properties are provided to control the minimum/maximum depth and the shape of the power curve used to define the sample/depth mapping.

The following properties are defined in the Depth Adjustment section.

  • Scale Depth is a Boolean that, when checked, uses the depth factor to scale the sample's existing depth value rather than overriding the depth with the depth factor.

  • Min Depth is the minimum depth adjustment.

  • Max Depth is the maximum depth adjustment.

  • Transfer Function is a function applied to the data which can be used to accentuate one area within the data while minimizing another.

  • Power controls the strength of the Transfer Function applied to each data value.

These parameters define the depth factor applied to the color returned by your program.

Min Depth and Max Depth control the range of the density/depth mapping. Samples with the minimum density value are mapped to Min Depth and samples with the maximum density value are mapped to Max Depth. Samples in the middle are mapped using linear interpolation between the 2 values based on their density value adjusted by Transfer Function and Power. If Scale Depth is unchecked, the result replaces the color's (HSV) Value. If Scale Depth is checked, the result is used to scale the color's (HSV) Value. See Transfer Function for a detailed description of Transfer Function and Power.

Lightness Adjustment

Fractal Science Kit - Orbital Color Controllers Properties Lightness Adjustment

The Lightness Adjustment section adjusts the (HSL) Lightness of the color returned by your program. The sample field density (Sample.Count) is mapped to a lightness factor. Properties are provided to control the minimum/maximum lightness and the shape of the power curve used to define the sample/lightness mapping.

The following properties are defined in the Lightness Adjustment section.

  • Scale Lightness is a Boolean that, when checked, uses the lightness factor to scale the sample's existing lightness value rather than overriding the lightness with the lightness factor.

  • Min Lightness is the minimum lightness adjustment.

  • Max Lightness is the maximum lightness adjustment.

  • Transfer Function is a function applied to the data which can be used to accentuate one area within the data while minimizing another.

  • Power controls the strength of the Transfer Function applied to each data value.

These parameters define the lightness factor applied to the color returned by your program.

Min Lightness and Max Lightness control the range of the density/lightness mapping. Samples with the minimum density value are mapped to Min Lightness and samples with the maximum density value are mapped to Max Lightness. Samples in the middle are mapped using linear interpolation between the 2 values based on their density value adjusted by by Transfer Function and Power. If Scale Lightness is unchecked, the result replaces the color's (HSL) Lightness. If Scale Lightness is checked, the result is used to scale the color's (HSL) Lightness. See Transfer Function for a detailed description of Transfer Function and Power.

Color Space Adjustment

Fractal Science Kit - Orbital Color Controllers Properties 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 Space is the color space you want to adjust. It can be set to HSL (Hue/Saturation/Lightness) or HSV (Hue/Saturation/Value). The HSL color space supports adjustments to the Hue, Saturation, and Lightness of the color. The HSV color space supports adjustments to the Hue, Saturation, and Value of the color.

  • Hue is a value added to the color's Hue. The value should be between -179 and 180.

  • Saturation is a value between -100 and 100 used to scale the color's Saturation. The value is given as a percentage change relative to the color's current Saturation. For example, 25 would increase the color's Saturation by 25 percent of the difference between full saturation and the current value. A value of -40 would reduce the color's Saturation by 40 percent.

  • Lightness is a value between -100 and 100 used to scale the color's Lightness. The value is given as a percentage change relative to the color's current Lightness. Lightness is unique to the HSL color model.

  • Value is a value between -100 and 100 used to scale the color's Value. The value is given as a percentage change relative to the color's current Value. Value is unique to the HSV color model.

  • Contrast is a value between 0.2 and 8 used to scale the color's Lightness/Value about the central value (Contrast Center). Values greater than 1 increase contrast. Values less than 1 decrease contrast. Lightness is used for the HSL color model. Value is used for the HSV color model.

  • Contrast Center is the central value about which Contrast scaling is applied.

Color Adjustment

Fractal Science Kit - Orbital Color Controllers Properties 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.

  • Brightness is a value added to each color's RGB components. The value should be between -1 and 1. Positive values brighten the color, negative values darken the color.

  • Contrast is a value between 0.2 and 8 used to scale each RGB component of the image data about the central value (Contrast Center). Values greater than 1 increase contrast. Values less than 1 decrease contrast.

  • Contrast Center is the central value about which Contrast scaling is applied.

  • Contrast Luminance is a Boolean that, when checked, scales the color's luminance rather than individual RGB values when applying contrast.

  • Gamma is a power factor applied individually to each color's RGB components. The value should be between 0.2 and 8. Values greater than 1 brighten the color. Values less than 1 darken the color.

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, Orbital 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 Variables

Several built-in variables are available to your instructions:

  • Color color
  • pixel

Controllers can access the above built-in variables. color is used to return the color computed by the program.

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 {
  R|Red  |H|Hue
  G|Green|S|Saturation
  B|Blue |L|Lightness |V|Value
  A|Alpha
}

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 Alpha value is used in conjunction with the Opacity Factor described above to blend colors from previous orbit points into the current point's color.

Example:

color:
 
  color = Gradient.Color(0, Sample.AttractorIndex)

This example calls the Gradient Function Gradient.Color to map the sample's normalized attractor index (Sample.AttractorIndex) 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:
 
  color = Gradient.Color(0, Value)
 
properties:
 
  option Value {
    type = SamplePointValue
    caption = "Value"
    default = Sample.AttractorIndex
  }

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.AttractorIndex which equates to the previous example if the user does not change it.

Example:

comment:
 
  Maps a sample point value to a gradient index.
 
color:
 
  color = Gradient.Color(ColorScheme, Value)
 
properties:
 
 option ColorScheme {
    type = GradientIndex
    caption = "Color Scheme"
    default = 0
    size = Large
  }
  option Value {
    type = SamplePointValue
    caption = "Value"
    default = Sample.AttractorIndex
  }

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:
 
  color = Color(R, G, B, 1)
 
properties:
 
  option R {
    type = SamplePointValue
    caption = "R"
    default = Sample.AttractorIndex
  }
  option G {
    type = SamplePointValue
    caption = "G"
    default = Sample.Speed
  }
  option B {
    type = SamplePointValue
    caption = "B"
    default = Sample.Acceleration
  }

This example maps 3 SamplePointValue options directly to the RGB components for Red, Green, and Blue.

Constants

The following constants are available to your instructions:

  • ViewportMagnification

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 Data

The 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 Orbital Controller programs:

  • Sample.AttractorIndex
  • Sample.AttractorIndexRaw
  • Sample.SymmetryIndex
  • Sample.SymmetryIndexRaw
  • Sample.Count
  • Sample.CountRaw
  • Sample.Speed
  • Sample.Acceleration
  • Sample.Angle
  • Sample.AngleRaw

Sample.AttractorIndexRaw is the attractorIndex set by the Orbital Equation. Sample.AttractorIndex is the normalized attractor index value.

Sample.SymmetryIndexRaw is the symmetry index from the Symmetry Transformation. Sample.SymmetryIndex is the normalized symmetry index value. If no Symmetry Transformation is active, these values are both 0.

Sample.CountRaw is the total number of orbit points that fall on the sample. Sample.Count is the normalized count.

Sample.Speed, Sample.Acceleration, and Sample.Angle are the normalized speed, acceleration, and angle for the orbit point. That is, let P, Q, and R be 3 consecutive orbit points. The following pseudo-code gives the speed, acceleration, and angle at Q:

PQ = Abs(P-Q)
QR = Abs(Q-R)

speed = (PQ + QR) / 2
acceleration = PQ - QR
angle = angle PQR such that 0 <= angle <= Math.PI

Sample.AngleRaw is the unnormalized angle given as a value between 0 and Math.PI.

 

Copyright © 2004-2016 Hilbert, LLC
All rights reserved