org.jscience.computing.ai.cellularautomaton
Class CellularAutomata

java.lang.Object
  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