org.jscience.computing.ai.cellularautomaton
Class CellularAutomata

java.lang.Object
  extended by org.jscience.computing.ai.cellularautomaton.CellularAutomata
All Implemented Interfaces:
Steppable, Visualizable
Direct Known Subclasses:
CellularAutomataLayered

public abstract class CellularAutomata
extends java.lang.Object
implements Visualizable, Steppable

This class provides the necessary functionality for simple 2-dimensional cellular automata. This class is not suitable for CAs that modify their world separately to their own states. See CellularAutomataLayered for this.

This class supports double-buffering to simulate synchronous updating of the CA world. See Conway's Life or Langton's Self-replicating loop as an example of this.

See Also:
CellularAutomataLayered

Field Summary
protected  int bufferPosition
          The buffer position (only 0 or 1).
protected  int bufferSize
          The size of the buffer (default = 1)
protected  int caSize
          Size of the individual CA cells in pixels.
protected  int[][][] caWorld
          The world array
protected  int caWorld_x
          Width of the CA world
protected  int caWorld_y
          Height of the CA world
protected  java.awt.Color clrBackground
          Background colour
protected  java.awt.Color clrGrid
          Colour of the grid, if used
protected  java.awt.Color[] clrWorld
          World colour
static int DOUBLE_BUFFERING
          Double buffering
protected  boolean doubleBuffering
          A quick way to ascertain whether double buffering is enabled
protected  boolean drawGrid
          Toggle to draw a grid - note this does NOT expand CA cell sizes, so caSize must be set to 3 or higher
static int ENCLOSED
          Enclosed geometry.
protected  int geometryType
          Geometry type.
static int INFINITE
          Infinite geometry (unsupported)
static int TORODIAL
          Torodial geometry.
protected static int X_AXIS
          Specifies translateGeometry(int,int) is to translate across the x-axis.
protected static int Y_AXIS
          Specifies translateGeometry(int,int) is to translate across the y-axis.
 
Constructor Summary
CellularAutomata()
          Default constructor.
CellularAutomata(int size_x, int size_y)
          Constructor with size initialization.
CellularAutomata(int size_x, int size_y, int options)
          Constructor with size initialization and setup options.
 
Method Summary
 void clearWorld()
          Clears the world.
abstract  void doStep()
          This abstract function is where the main workings of the CA should take place.
 void drawGrid(boolean dg)
          Set or reset the drawGrid flag.
 void flipBuffer()
          This function must be called when using double-buffering to swap the buffers around.
 java.awt.Color getBackgroundColor()
          Retrieve the background color.
 int getCASize()
          Returns the CA size
 int getGeometry()
          Retrieve the current geometry type
 int getSizeX()
          Return the world x-size.
 int getSizeY()
          Return the world y-size.
 int getWorldAt(int pos_x, int pos_y)
          Returns the pixel state at a given position.
abstract  void init()
          This abstract function is where the initialization of the CA should take place.
static void iterateCA(CellularAutomata ca, int iterations, int snapshot, java.lang.String prefix, int caSize)
          This is a default testing method that many of the cellular automata main methods use.
static void iterateCA(CellularAutomata ca, java.lang.String[] args)
          This method calls iterateCA but with the parameters encoded as a String array, ideally suited to be passed from the command-line.
 void render(java.awt.Graphics graphics, int pw, int ph)
          This is the default function for drawing the CA world.
 void reset()
          Reset the world.
 void setBackgroundColor(java.awt.Color back)
          Set the background colour of the CA.
 void setCASize(int cas)
          Sets the CA size.
 void setGeometry(int g)
          Sets the geometry type.
 void setWorldAt(int pos_x, int pos_y, int s)
          Sets the world at the given position to a given state.
 void setWorldAtEx(int pos_x, int pos_y, java.lang.String cellStates)
          This function sets a group of cells according to a specially formatted string.
 void setWorldAtRelative(int pos_x, int pos_y, int ds)
          Set the world state relative to its current state.
 void setWorldColors(java.awt.Color[] colors)
          Similar to setWorldColour, but accepts an array of colours.
 void setWorldColour(int world, java.awt.Color colour)
          This function sets the various world colours used by the CA.
 void setWorldSize(int size_x, int size_y)
          Sets the world size.
protected  int translateGeometry(int pos, int axis)
          Translates a coordinate to the specified geometry.
 void writeImage(java.lang.String filename, int width, int height)
          This default function writes a PNG image of the CA world.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

INFINITE

public static final int INFINITE
Infinite geometry (unsupported)

See Also:
Constant Field Values

TORODIAL

public static final int TORODIAL
Torodial geometry. Coordinates are wrapped around.

See Also:
Constant Field Values

ENCLOSED

public static final int ENCLOSED
Enclosed geometry. Coordinates are truncated, not wrapped.

See Also:
Constant Field Values

DOUBLE_BUFFERING

public static final int DOUBLE_BUFFERING
Double buffering

See Also:
Constant Field Values

X_AXIS

protected static final int X_AXIS
Specifies translateGeometry(int,int) is to translate across the x-axis.

See Also:
translateGeometry(int, int), Constant Field Values

Y_AXIS

protected static final int Y_AXIS
Specifies translateGeometry(int,int) is to translate across the y-axis.

See Also:
translateGeometry(int, int), Constant Field Values

caWorld

protected int[][][] caWorld
The world array


caWorld_x

protected int caWorld_x
Width of the CA world


caWorld_y

protected int caWorld_y
Height of the CA world


geometryType

protected int geometryType
Geometry type. Currently, the classes only support torodial geometry.


clrBackground

protected java.awt.Color clrBackground
Background colour


clrWorld

protected java.awt.Color[] clrWorld
World colour


clrGrid

protected java.awt.Color clrGrid
Colour of the grid, if used


caSize

protected int caSize
Size of the individual CA cells in pixels. For rendering purposes.


bufferSize

protected int bufferSize
The size of the buffer (default = 1)


doubleBuffering

protected boolean doubleBuffering
A quick way to ascertain whether double buffering is enabled


drawGrid

protected boolean drawGrid
Toggle to draw a grid - note this does NOT expand CA cell sizes, so caSize must be set to 3 or higher


bufferPosition

protected int bufferPosition
The buffer position (only 0 or 1).

Constructor Detail

CellularAutomata

public CellularAutomata()
Default constructor. The defaults are torodial geometry, 2 pixel per CA cell, a light gray background (outside CA world) and a light gray grid (not drawn by default).


CellularAutomata

public CellularAutomata(int size_x,
                        int size_y)
Constructor with size initialization. See #CellularAutomata for default settings.

Parameters:
size_x - width of the world
size_y - height of the world

CellularAutomata

public CellularAutomata(int size_x,
                        int size_y,
                        int options)
Constructor with size initialization and setup options. See #CellularAutomata for default settings.

Parameters:
size_x - width of the world
size_y - height of the world
options - possible additional options (such as double buffering)
Method Detail

getSizeX

public int getSizeX()
Return the world x-size. The value returned is the number of cells the CA world has across its width.

Returns:
world width
See Also:
caSize

getSizeY

public int getSizeY()
Return the world y-size. The value returned is the number of cells the CA world has across its height.

Returns:
World height
See Also:
caSize

setWorldSize

public void setWorldSize(int size_x,
                         int size_y)
Sets the world size. This will allocate the necessary memory for the CA world, as well as set the caWorld_x/y member fields.

Parameters:
size_x - The new world size (width)
size_y - The new world size (height)

setCASize

public void setCASize(int cas)
Sets the CA size. CA Size is the number of pixels each CA cell is to use when rendered. For example, setCASize(4) causes each cell to be rendered as a 4x4 square.

Parameters:
cas - cell size (in pixels)

getCASize

public int getCASize()
Returns the CA size

Returns:
The CA size in pixels
See Also:
setCASize(int)

drawGrid

public void drawGrid(boolean dg)
Set or reset the drawGrid flag. This causes the render function to draw a grid around the CA cells.

Parameters:
dg - true to draw the grid
See Also:
render(Graphics,int,int)

clearWorld

public void clearWorld()
Clears the world. All cell states are set to zero. This includes the buffer if double-buffering is enabled.


getWorldAt

public int getWorldAt(int pos_x,
                      int pos_y)
Returns the pixel state at a given position. This function uses translateGeometry before accessing the array; this means for torodial geometry you may pass a number out of bounds of the CA world, and getWorldAt will wrap around the world.

Parameters:
pos_x - x position of cell state to return
pos_y - y position of cell state to return
Returns:
Cell state
See Also:
translateGeometry(int,int)

setWorldAt

public void setWorldAt(int pos_x,
                       int pos_y,
                       int s)
Sets the world at the given position to a given state. This function uses translateGeometry before accessing the array; this means for torodial geometry you may pass a number out of bounds of the CA world, and setWorldAt will wrap around the world.

Parameters:
pos_x - X-position of cell to set
pos_y - Y-position of cell to set
s - State to use

setWorldAtRelative

public void setWorldAtRelative(int pos_x,
                               int pos_y,
                               int ds)
Set the world state relative to its current state.

Parameters:
pos_x - the x-position of the cell.
pos_y - the y-position of the cell.
ds - the delta value to add to the world state.

setWorldAtEx

public void setWorldAtEx(int pos_x,
                         int pos_y,
                         java.lang.String cellStates)
This function sets a group of cells according to a specially formatted string. Rows of cells are delimited by semi-colons, whilst individual strings are separated using a comma. For example, a glider in Life might be represented by: "0,1,0;0,0,1;1,1,1". Row strings do not have to be of equal length, but all positions are calculated according to the first cell.

Parameters:
pos_x - the x-position to start the group of cells
pos_y - the y-position to start the group of cells
cellStates - the specially formatted string

translateGeometry

protected int translateGeometry(int pos,
                                int axis)
Translates a coordinate to the specified geometry.

Parameters:
pos - The coordinate
axis - The axis to translate around
Returns:
Translated coordinate
See Also:
geometryType, X_AXIS, Y_AXIS

setGeometry

public void setGeometry(int g)
Sets the geometry type. Currently only torodial geometry is supported.

Parameters:
g - the geometry type

getGeometry

public int getGeometry()
Retrieve the current geometry type

Returns:
the geometry type in use

doStep

public abstract void doStep()
This abstract function is where the main workings of the CA should take place. Every iteration, this function is called causing the CA to advance a step.

Specified by:
doStep in interface Steppable

init

public abstract void init()
This abstract function is where the initialization of the CA should take place. This function is also called when the CA is reset, so one-time initialization should remain in the constructors.

Specified by:
init in interface Steppable

setBackgroundColor

public void setBackgroundColor(java.awt.Color back)
Set the background colour of the CA. Note that this colour is not the default world colour, but the colour rendered outside of the CA world area. This is particularly pertinent when displaying CAs in applets.

Parameters:
back - the background colour to be used
See Also:
setWorldColour(int,Color)

getBackgroundColor

public java.awt.Color getBackgroundColor()
Retrieve the background color. Remember, this is the color that is used for area outside the CA.

Returns:
the background color.

setWorldColour

public void setWorldColour(int world,
                           java.awt.Color colour)
This function sets the various world colours used by the CA. Each cell holds one of a possible 256 states, this function sets the colours for these states. Note that setWorldColour(0, Color) sets the default world colour.

Parameters:
world - the state to set
colour - the colour to use

setWorldColors

public void setWorldColors(java.awt.Color[] colors)
Similar to setWorldColour, but accepts an array of colours. This function is especially useful when using the Gradient helper class.

Parameters:
colors - the array of colours to be used for the world states.
See Also:
Gradient

flipBuffer

public void flipBuffer()
This function must be called when using double-buffering to swap the buffers around. Remember to do this when after (or within) init and doStep.


render

public void render(java.awt.Graphics graphics,
                   int pw,
                   int ph)
This is the default function for drawing the CA world. It centres the CA world within the graphics context, and draws each cell as a square caSize large. The render function will also draw a grid, if requested.

Specified by:
render in interface Visualizable
Parameters:
graphics - the graphics context
pw - the width of the context
ph - the height of the context
See Also:
caSize

writeImage

public void writeImage(java.lang.String filename,
                       int width,
                       int height)
This default function writes a PNG image of the CA world.

Specified by:
writeImage in interface Visualizable
Parameters:
filename - the filename to use for the image
width - the width of the image
height - the height of the image

iterateCA

public static void iterateCA(CellularAutomata ca,
                             java.lang.String[] args)
This method calls iterateCA but with the parameters encoded as a String array, ideally suited to be passed from the command-line.
  1. number of iterations in total (default 100,000)
  2. snapshot frequency (default 10,000)
  3. image prefix (default g5jdk)
  4. ca size

Parameters:
ca - the CA class to use
args - the arguments to be used (see above)
See Also:
iterateCA(CellularAutomata,int,int,String,int)

iterateCA

public static void iterateCA(CellularAutomata ca,
                             int iterations,
                             int snapshot,
                             java.lang.String prefix,
                             int caSize)
This is a default testing method that many of the cellular automata main methods use. It will iterate over a certain number of steps, writing snapshots to disk.

Parameters:
ca - an instance of the cellular automata class.
iterations - the total number of iterations.
snapshot - the number of iterations before a snapshot is taken.
prefix - the prefix to apply to the files.
caSize - the size of the CA cells.

reset

public void reset()
Reset the world. Defaults to calling init again.

Specified by:
reset in interface Steppable