Static Cube Images Generator ver. 0.2

Table of contents

  1. Introduction
  2. Getting started
  3. Usage
    1. First image
    2. Configuration
    3. Description files
    4. Names in SCIG
    5. Colors
    6. Color schemes
    8. Specifications
    9. Engines
    10. Collections
  4. Contact

This page may not display properly if your browser does not support XHTML. Please get firefox.

  1. Introduction
  2. SCIG is a PHP script which allows to create static representations of Rubiks Cube and similar puzzles. It is highly customizable and has many useful features like caching and drawing many cubes on one image.

    Main features:

  3. Getting started
  4. To run SCIG on your web server you need to have PHP and GD installed. Then you need to get source code. The best place for this would be SCIG sourceforge site(recommended). You can also use SVN repository (the newest possible version), but the code there can be unstable. To get SVN version of SCIG run:
    svn co scig
    To do this you must have SVN installed.

    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.

  5. Usage
  6. 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.

    1. First image
    2. 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.


      If you want a different algorithm just change data:


    3. Configuration
    4. 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.
      You probably want this set to false.
      logs dir
      Directory for storing logs. Must be writeable if debug is true.

    5. Description files
    6. 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
            - main:
              x:                0
              y:                0
              width:            100
              height:           100
              view:             3face
              scheme:           BOY
          And the URL:
          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.
          - 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

    7. Names in SCIG
    8. 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.

    9. Colors
    10. 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.

    11. Color schemes
    12. 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
        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.

    14. 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 enabledSmart arrows disabled

    15. Specifications
    16. 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:
          - piecetype:
            - [stickerofpiece, stickerofpiece...] # stickers of one piece
            - [stickerofanotherpiece...] # stickers of another piece
            ... # next pieces
          - anotherpiecetype:
        Let's look at Rubiks Cube 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:
          - facename
            - sticker1
            - sticker2
          - anotherfacename

    17. Engines
    18. 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:
        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.

    19. Collections
    20. 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:
            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 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 -->

  7. Contact
  8. You can contact me via email (tomahawk_pl at Remember that you can report bugs and feature requests on SCIG sourceforge page. Logo