SoundSpectrum music visualization software
     
  Documentation
 
Basic
     Introduction
   FAQ
   Troubleshooting
   License Agreement
   Contact
   About

 
Advanced
     Standalone Use
   Intro to Scripting
   Advanced Scripting
   Version History

 

  Scripting SoftSkies Part I

 
 

      SoftSkies' scripting capabilities allow you to specify the appearance and behavior of the SoftSkies visualizer dynamically. Scripts written for SoftSkies, here referred to as "configs", allow you to create unique scene configurations on the fly using your own custom algorithms or by incorporating features from existing SoftSkies config files.


A Very Quick Introduction to Python

     All of the config files discussed in this document use the Python programming language "under-the-hood", but there's no need to know Python to start writing config files. Simple config files need only execute the simple functions outlined in this file and do not require any Python knowledge. At the same time, advanced users will find that Python provides a very powerful way to extend the capabilities of the visualizer indefinitely. This document does describe some basic Python functionality required to implement simple configs for the visualizer, but it is not meant as a general introduction to the Python language. More information about Python can be found at http://www.python.org.

     Two simple notes about Python before continuing: first, Python is very sensitive to "whitespace" (spaces, tabs and newlines). Be careful to use spaces and tabs as they are shown in this document–code may not work if whitespace is missing or if excess whitespace is included. Second, any line in Python beginning with a "#" character (a "hash" or "pound") is considered a comment and does not effect the way a program runs. The examples below are thus commented using the "#" character to explain why things work a certain way.


The Simplest Config

     The simplest config files simply specify a fixed set of cloud parameters. We'll begin with a quick demonstration of how to create a simple config. This demonstation config will simply change the color of the clouds. Follow these instructions to create your first custom config:

  • Locate your SoftSkies folder
  • Go into the Configs folder
  • Create a text file named "MyConfig.config"
  • Add the following line to the file:
         SoundSpectrum.SetRGBColor( "cloud_color", 0, 0, 0 )
  • Save the config file–make sure the extension .config is used (some editors may try to change the extension!)
  • Launch SoftSkies and use the SoftSkies menu to go to the "Skies Library"
  • Select the "MyConfig" button–the clouds should fade to black!

More Information on Simple Configs

     The simple config presented in the previous step simply sets the color of the clouds. Most configs modify a larger set of parameters. This section describes in more detail how variables are set. There are two main types of SoftSkies parameters: numerical parameters and color parameters. Numerical parameters are set using the function SoundSpectrum.SetParameter(). This function is passed either two or three inputs (also known as "arguments") which specify its behavior. The first two input values specify the name of the parameter being set (in quotes) and the new value for the parameter. The third input is optional: all parameter settings in the visualizer work by fading parameters over time and the third value, if it is given, specifies the number of seconds the fade should take. The default fade duration, if none is given, is 3 seconds. The following two examples show how a parameter is set both with and without a duration value:

# This will set the camera angle to 45 degrees
# over the course of 3.0 seconds
SoundSpectrum.SetParameter( 'cloud_camera_angle', 45 )

# In this example, we want the change to go faster,
# so we specify a shorter fade time:
SoundSpectrum.SetParameter( 'cloud_camera_angle', 45, 1.0 )

     These two different ways of calling the function SoundSpectrum.SetParameter() are summarized in the following line:

SoundSpectrum.SetParameter( 'parameter_name', value [, duration] )

The text in italics indicates that the text should be replaced with the value you wish to provide to the function. The value shown in brackets ( [] ) indicates that it is optional. This convention is used throughout this documentation to describe how functions are used.

     Color parameters are specified using a similar technique, except that color values each consist of three components and thus use different functions: SoundSpectrum.SetHSVColor() and SoundSpectrum.SetRGBColor(). Both of these functions use 3 color components with values from 0.0 to 1.0 to determine the color for a parameter. The two functions use different ways of thinking about colors, though both ways can be used to express any color.

     SoundSpectrum.SetHSVColor() uses the "hue saturation value" color model in which the "hue" specifies color, "saturation" specifies how vibrant the color is, and "value" specifies the brightness of the color. SoundSpectrum.SetRGBColor() sets colors using the "red green blue" color model in which the 3 color components are specified as red, green and blue intensity values respectively. Either of the functions may be used for any color parameter, though typically, certain tasks are more easily accomplished using one method or the other. As with simple scalar parameters, color changes fade over a certain period of time. An optional duration argument specifies over how many seconds a transition should occur:

SoundSpectrum.SetHSVColor( 'color_parameter_name', hValue, sValue, vValue [, duration] )
SoundSpectrum.SetRGBColor( 'color_parameter_name', rValue, gValue, bValue [, duration] )


     Some examples of these functions are shown below:

# Set the cloud color to 1, implicitly over
# 3.0 seconds (since we don't specify a value)
SoundSpectrum.SetRGBColor( "cloud_color", 0, 0, 1 )

# Set the cloud lighting factor to 4.0 over 1.1 seconds
SoundSpectrum.SetParameter( "cloud_lighting_factor", 4.0, 1.1 )

# Set the cloud camera angle to 0 immediately!
SoundSpectrum.SetParameter( "cloud_camera_angle", 0.0 )


     A full list of parameters which can be used with SoftSkies is shown in the following section.



List of User-Modifiable Cloud Parameters and Their Meanings

     Using the simple functions outlined in the previous section, you can modify all of the SoftSkies scene settings. This section describes all of the user modifiable parameters. The variables are divided into two groups: color parameters and numerical parameters. In parenthesis are the names of the parameters as they appear in the SoftSkies Skies Builder.

     The first table shows the color parameters which can be customized in SoftSkies. All colors can be expressed either as HSV or RGB color values with each element in the range from 0.0 to 1.0.

Parameter Name Description
cloud_color The color of the overall cloud bodies (Cloud Color)
cloud_shade_color The color of the shadows on the cloud surfaces (Cloud Shading Color)
cloud_primary_background_color The primary background color (Primary Background Color)
cloud_secondary_background_color The secondary background color (Secondary Background Color)

     This table describes all of the user-modifiable numerical parameters. Also shown is the recommended range of values for each parameter. The recommended range is the range that is used by the standard SoftSkies configs and is considered to be capable of producing reasonable cloud behaviors and appearances. You may experiment with values outside of the ranges given here with the understanding that it may produce undesirable results. The SoftSkies engine also implements its own limits which prevents parameters which may cause instabilities or internal errors. For this reason, values set far outside of the recommended parameter range may not have any effect at all.

Parameter Name Min. Value Max. Value Description
cloud_camera_angle 0.0 6.28 The angle from the camera to the sky-plane (Cloud Angle)
cloud_copy_constant 0.45 0.6 A measure of how rapidly cloud vapor accumulates (Cloud Accumulation Rate)
cloud_lighting_angle 0.0 6.28 The angle of the sun relative to the clouds (Lighting Angle)
cloud_lighting_factor 0.3 0.6 A measure of how strongly lighting effects the clouds (Lighting Factor)
cloud_horizon_level 0.0 1.0 The height of the cloud horizon
cloud_wind_intensity 0.15 0.35 The intensity of wind (Wind Intensity)
cloud_wind_direction 0.0 6.28 The direction of wind (Wind Direction)
cloud_warping_factor 0.085 0.135 The level of cloud vapor distubance (Cloud Warping Factor)
cloud_warping_speed 0.0 5.0 The velocity of cloud vapor disturbances (Cloud Warping Speed)
cloud_background_level 0.3 0.6 The intensity of the background vapor (Background Level)
cloud_background_warping_factor 0.5 1.0 The level of background vapor disturbance (Background Warping Factor)
cloud_layer_offset 0.002 0.012 The distance offset between cloud layers (Cloud Layer Offset)
cloud_max_concentration 0.045 1.0 The maximum concentration of cloud vapor (Maximum Cloud Vapor Level)
cloud_source_size 1.0 2.0 A value determining the size of invisible sources which introduce vapor (Cloud Source Size)
cloud_turbulence_intensity 0.0 20.0 A value determining the level of disturbance in the wind (Wind Turbulence)
cloud_threshold_factor 8.0 12.0 A value determining what concentration of cloud vapor is visible (Cloud Threshold Factor )
 
 

Intermission

 
       Using only the simple concepts outlined above, you can begin to create simple configs which change the appearance and behavior of clouds in the SoftSkies visualizer. Before continuing, it may be useful to make a copy of the included config file "Example Config.config" (in your "Configs" directory), edit it, and examine how changes to the config file effect the visualizer. Add new lines of code to set some of the other parameters described above as well. Any config file in the "Configs" directory will automatically be added to the "Skies Library" menu.

 

Terms of Use  |   Privacy Policy  |   About Us  |   Feedback

© 2017 SoundSpectrum, Inc.