Static Cube Images Generator ver. 0.2

Introduction

• many views of the same puzzle on one image
• defining your own color schemes and views
• displaying state of the puzzle before or after execution of an algorithm
• defining state of the puzzle explicitely
• drawing arrows
• configuring with YAML
• caching
• handling collections of algorithms
• possibility to add new puzzles
• Joomla mambot

Getting started

svn co https://svn.sourceforge.net/svnroot/scig/trunk scig

Place the scig directory in a place you can access via web server and point your browser to file sample.php in doc directory. If all images are displayed correctly then you have successfully installed SCIG. If you don't see one or more of the images make sure you have PHP and PHPGD installed. Also, if you got the source from SVN, you may need to set use cache option in configuration.yml file to false. Contact me if you encounter other problems.

Usage

In most cases you will have to know only first three sections of this chapter. Rest will be needed only when you will want to create something more complicated or totally new. Also go through existing SCIG files if you have problems understanding any of the SCIG features.

First image

Everytime you run scig.php you can specify two parameters: desc and data. The first one is the name of the description file without the yml extension. Description files are placed in directory descriptions. They contain information about general structure of an image that will be generated. Read more about them here. The data can be one of two things: a state of the puzzle or an algorithm.

Let's say you want to create nice image for your pr0 T permutation. Then your data will be your algorithm: RUR'U'R'FR2U'R'U'RUR'F'. You would like to see top face with arrows and front view of the cube. Luckily there already exists a description file (sample/pll) which describes such situation, let's use it.


scig.php?desc=sample/pll&data=RUR'U'R'FR2U'R'U'RUR'F'
If you want a different algorithm just change data:
scig.php?desc=sample/pll&data=M2UM2U2M2UM2

Configuration

You can configure general SCIG behaviour in file configuration.yml. YAML is used here (like almost everywhere in SCIG). Don't worry, you don't have to fully learn new language. YAML is extremaly simple and readable so actually no explanation is needed.

use cache

Set it to true if you want SCIG to cache images (in most cases you want this to be enabled). Everytime SCIG will be run it will check if the same image was created before and is stored in cache. If it is it will be used and won't have to be created. Cached file won't be used if description file was modified. When this is set to true the directory specified as cache dir must be writeable.
cache dir

Directory where cached files will be stored. Must be writeable if use cache is true.
debug

You probably want this set to false.
logs dir

Directory for storing logs. Must be writeable if debug is true.

Description files

Description files are placed in descriptions directory. They contain general information about the created image. Elements that must appear in a description file:
• puzzle
  
  The name of the puzzle for which the image will be generated, for example Rubiks Cube. See Names in SCIG.
• mode
  
  Can be one of these: normal, effect, reverse.

  • normal
    
    You want to specify state of the puzzle on your own. You must check engine's documentation to read about used format. Then you must place the description of that state in data parameter. For example you want an image where two edges of a Rubiks Cube are swapped (this position is impossible to achieve by any algorithm so you must use normal mode and define state manually). The description file (sample/simple.yml) might look like this:

    width:          100
    height:         100
    mode:           normal
    puzzle:         Rubiks Cube
    parts:
      - main:
        x:                0
        y:                0
        width:            100
        height:           100
        view:             3face
        scheme:           BOY

    And the URL:

    scig.php?desc=sample/simple&data=1.0.2.3.4.5.6.7.8.9.10.11.0.1.2.3.4.5.6.7.0.1.2.3.4.5

    The result would be: If mode is normal then the data parameter is divided into parts (separated by dot) and these parts are passed on to the engine which creates array readable by SCIG.
  • effect
    
    It creates a state of a puzzle after execution of an algorithm specified in the data parameter. Notice that you can use parentheses in algorithm (they don't change behaviour of the script, but the algorithm written in this way can be displayed when you are using Collections).
  • reverse
    
    It creates a state of a puzzle before execution of an algorithm.
• width
  
  The width of created image.
• height
  
  The height of created image.
• parts
  
  This element defines parts of an image. Every image can have unlimited amount of them. The description of every part starts with a dash and a part name. It must contain following elements:

  • x
    The x coordinate of part's left-top corner.
  • y
    The y coordinate of part's left-top corner.
  • width
    The width of the part.
  • height
    The height of the part.
  • scheme
    Name of the color scheme used by the part.
  • view
    Name of the view used by the part.

  Example:

  parts:
    - normal:
        x:                0
        y:                0
        width:            100
        height:           100
        view:             3face
        scheme:           BOY
    - top:
        x:                200
        y:                0
        width:            100
        height:           100
        view:             top
        scheme:           BOY
    - blackandwhite:
        x:                300
        y:                0
        width:            100
        height:           100
        view:             top
        scheme:           blacktop

Names in SCIG

In SCIG there are few conventions concerning names of files, directories and classes. They allow SCIG to figure out these names so you won't have to define them everywhere. Everything starts with the puzzle name that is given in the description file. For example if its Rubiks Cube then SCIG looks for files rubiks_cube.yml in specs directory for puzzle specification and rubiks_cube.php in engines for puzzle engine. The engine class name should be RubiksCube. Also all color schemes and views for this puzzle should be in subdirectory rubiks_cube in schemes and views directories. Color schemes and views names are lowercased when SCIG looks for their files, so BOY should be in a file boy.yml.

Colors

All colors used by SCIG are defined in file colors.yml. Definition of a color looks like this:

color name: red green blue

where red, green and blue are numbers from range 0-255. Later (color schemes) you don't have to remember these numbers, you just use color names. It is important to have transparent color defined, so it can be used in views in some special cases.

Color schemes

Color schemes are files which describe the colors of stickers. They are placed in directory schemes/puzzlename. Of course YAML is used in these files. Let's see an example (Fridrich PLL):

all:    dark gray
U:      yellow
stickers:
  red: FU FRU FLU
  green: RU RUF RUB
  orange: BU BRU BLU
  blue: LU LUF LUB

If all appears in file it is always processed first and sets color of all stickers to the one given. In the example above first we set all stickers to dark gray. Then SCIG reads pairs facename: color and sets all stickers on that face to the given color. Next are pairs stickername: color which set one sticker to given color. Remember that if theres a sticker which has the same name as face (for example U is a sticker and a face on Rubiks Cube) SCIG will always consider it a face. You should use stickers to set colors of such stickers. stickers is always read at the end, you can set with it's help many stickers to one color. Of course you could define colors of all stickers with stickers, but it would take much more time and effort. Remember to color all stickers (with all) first to the most common color, then color faces and stickers as last.

There are also few special elements which can appear in color scheme:

• default
  
  SCIG doesn't allow some stickers (see views) to be transparent. You can specify default color which will be used instead of transparent.
• arrows
  
  Color of arrows if they will be drawn.

Views

Views' files are placed in directory views/puzzlename. Their function is to describe the appearence of a puzzle. They can contain:
• use
  
  Include contents of another view file. Useful when you want to use same lines or/and stickers and just make a minor change.
• width
  
  This is the width that will mean 100% of view's width. Of course all views will be rescaled by the user all the time in description files so this doesn't mean much. Use whatever suits you. This is just used inside view's description when you specify coordinates.
• height
  
  Same as width.
• base
  
  The base image that will be used as a background. Image must be a PNG and should be placed in directory bases. You should specify filename without png extension. For example if you set base to top SCIG will look for a file top.png in views/puzzlename/bases directory. If width or height is unset then both will be set to PNG's width and height. If they are set the base image will be rescaled.
• lines
  
  List of lines to draw. Definition of each line:

    - beginx beginy endx endy [color]
  

  Where beginx, beginy, endx, endy should be numbers >0 and <width (color is not required). By default all lines are black. If you want to change their color just specify it as a 5th element. All following lines will use new color.
• stickers
  
  This section defines places on the image where stickers will be drawn. Every element of the list should like like this:

    - sticker coord1x coord1y [coord2x coord2y [coord3x coord3y...]]
  

  It means you always must specify sticker and two coordinates, but you can more. If you will give two coordinates SCIG will fill the image at the given coordinates with sticker's color. These coordinates will also be use to draw arrows. Four coordinates mean that you want to draw rectangle filled with sticker's color. Center of the rectangle will be used to draw arrows. If more coordinates are specified SCIG will consider them as filled polygon vertices. It will calculate it's center of mass to draw arrows.
• arrows
  
  List of stickers for which arrows can be drawn. For example:

  arrows: UF UR UB UL

  will draw arrows between edges of top layer. SCIG will not care about orientation of a piece.
• disable smart arrows
  
  By default this is false, but if you set it to true SCIG will care about orientation of a piece and will not draw arrows if pieces are incorrectly oriented. Example:

  arrows: UF UR UB UL UFR UFL UBR UBL

  Smart arrows enabled	Smart arrows disabled

Specifications

Specification files describe the structure of the puzzle. They should be located in directory specs and contain two sections:
• stickers
  
  This section should have the following format:

  stickers:
    - piecetype:
      - [stickerofpiece, stickerofpiece...] # stickers of one piece
      - [stickerofanotherpiece...] # stickers of another piece
      ... # next pieces
    - anotherpiecetype:
      ...

  Let's look at Rubiks Cube stickers:

  stickers:
    - edges:
      - [UF, FU]
      - [UR, RU]
      - [UB, BU]
      - [UL, LU]
      - [DF, FD]
      - [DR, RD]
      - [DB, BD]
      - [DL, LD]
      - [FR, RF]
      - [FL, LF]
      - [BR, RB]
      - [BL, LB]
    - corners:
      - [UFR, FRU, RUF]
      - [UFL, FLU, LUF]
      - [UBR, BRU, RUB]
      - [UBL, BLU, LUB]
      - [DFR, FRD, RDF]
      - [DFL, FLD, LDF]
      - [DBR, BRD, RDB]
      - [DBL, BLD, LDB]
    - centers:
      - U
      - D
      - F
      - B
      - R
      - L
  

• faces
  
  Here you place information which sticker belongs to which face. The format is as follows:

  faces:
    - facename
      - sticker1
      - sticker2
      ...
    - anotherfacename
      ...
    ...

Engines

Engines are PHP classes (sorry, no YAML here ;p). They're purpose is to generate the state after of before execution of an algorithm. It should have at least two public methods:
• process
  
  This method should accept two parameters. First being the algorithm and second the mode (effect or reverse). It should return an array with indices and values being sticker names. For example:

  $state=$engine->process($alg,$state);
  

  Then for any stickername $state[stickername] should be also a sticker name and it means there's a $state[stickername] in stickername's place.
• stickerize
  
  Accepts one parameter - state of the puzzle but in the format that could be used by human and should return the same as the process method. It is up to engine writer to create such a readable format and document it. This format would be used when mode is set to normal.

Collections

SCIG allows to pretty easily display collections of algorithm. For example 21 PLL algorithms. If you want to use that feature your application should include file collection.php and you should create template file (in directory templates) and collection description (collections). Then you should simply use method renderCollection(collection). Where collection is filename of the collection description file without extension.

Collection descriptions

• description
  
  Name of the description file that will be used when generating images.
• template
  
  Name of the template that will be used, if this is not specify SCIG assumes that it is the same as description.
• algorithms
  
  In this section you define algorithms that will be displayed. The format is as follows:

  algorithms:
    -
      data: algorithm # where algorithm is for example RUR'
      [other options]
    - data: algorithm2
      [other options]
    ...

  data is required and is an algorithm or state for which an image will be generated.[other options are pairs option: value which can be used in templates. For example if you also want to display a short description of an algorithm you can specify description: Very nice alg and then use {DESCRIPTION} in template.

Templates

Templates are files with xtpl extension. They're basically the same as HTML except you can insert variables in there. SCIG uses XTemplate as template engine, however only basic features are used now (maybe that'll change). Your template should define main template so probably it will look like this:

<!-- BEGIN: main -->
template content
<!-- END: main -->

Remember that you can use here variables defined in collection file (uppercase). SCIG will insert the image in the place of {IMAGE}. Example:

<!-- BEGIN: main -->
<tr><td align="center"><letter>{NAME}</letter></td><td align="center"><img src="../{IMAGE}"></td>
<td align="center"><alg>{ALG}</alg></td><td><comment>{DESCRIPTION}</comment></td></tr>
<!-- END: main -->

Contact