rasterscript version 0.6.1 - README.txt

Rasterscript(TM) is a piece of software of questionable application, yet with a degree of coolness.
It is written for the Simple Inkscape Scripting (SIS) extension used with Inkscape. For details,
see:

SIS Github page: https://github.com/spakin/SimpInkScr
SIS Inkscape page: https://inkscape.org/~pakin/%E2%98%85simple-inkscape-scripting

---------------------------------------------------------------------------------------------------
Version 0.7 update:
- now reads config from configuration file (default: rasterscript.cf) exclusively
---------------------------------------------------------------------------------------------------

Rasterscript creates a multicolor background grid consisting of squares or circles (called cells),
placed on an Inkscape layer. A layer of multicolor squares or circles (eyes) is created above it.
The whole thing can be topped by a 'raster': a single-color layer with round holes in it.
Rasterscript atarted out as an experiment with random colors, and the colors used for cell and eyes
are therefore in principle entirely random. The set of available colors can be limited by supplying
a palette file. For complete cntrol over the colors rendered, a 'matrix file' can be supplied.

Rasterscript will not paint beyond the supplied page boundaries, unless a matrix file is used, in
which case the user is expected to make the various different values match. In that case there is
no limiit to the extent to which the resulting image may exceed the page boundaries. The relevant
parameters are:

- cell size, which can be considered the basic output unit
- page height and width

The number of rendered rows an columns depends the values set, except again with a matrix file, in
which case these values are implicitly present in the matrix itself. An overview of settable
parameters and configuration files should clarify the various issues involved.

Runtime parameters are set in the User section within the script itself.


1. Page

The intended page dimensions can be set.

pagewidth = 1000				default: the width of the opened page in Inkscape
pageheight = 1000				default: the height of the opened page in Inkscape

If these are left commented out, the page dimensions of the opened document are used.


2. Cells

The default cell shape is a square. Setting this to 'circles' generally only makes sense if a
raster is disabled. In that case the background will show transparent parts, with the circles
filling the cells as much as possible, and adjacent ones therefore touching one another. A degree
of cell padding can be achieved by using a transparent raster instead.

The number of cells produced varies: rasterscript will adapt the number of rows and columns to make
the output stay just within the page boundaries (once again: unless a matrix is supplied). The cell's
stroke color can be set, together with a stroke width, to produce a kind of line art effect, which
in the case of cells will only be visible without a raster being created, or with the raster layer
being hidden in inkscape. The ability to hide layers in the document adds even more flexibility to
rasterscript's output.

Apart from RGB values, all numeric ones are supposed to be in px.

----------------------------------------------------------------------------------------------------
Note: RGB values must not be preceded by a prefix like '#' or '0x'. These should never occur
among the user-supplied input. Not anywhere.
----------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------------------
Note: Settings with a default value can be commented out for operational convenience.
----------------------------------------------------------------------------------------------------

cellshape = 'circle'				default: square
cellsize = 200					no default
cellstrokecolor = 'ffffff'			default: 000000 (black)
cellstrokewidth = 4				default: 0


3. Eyes

Most parameters are analogous to those of cells. Setting the 'wobbly' flag will cause eye positions
to be randomized within certain limits.

eyeshape = 'square'				default: circle
eyesize = 80					no default
eyestrokecolor = 'ffffff'			default: 000000 (black)
eyestrokewidth = 4				default: 0
wobbly = 'yes'					default: no


4. Raster

The raster covers the background and eyes. Background cells and eyes are (at least) partially
visible through holes in the raster. Setting the raster color to 'transparent' will make the
areas which would be covered by the raster transparent. It is not the same as simply hiding
the raster layer, as this would reveal precisely these areas.

raster = 'no'					default: yes
holeshape = 'square'				default: circle
holesize = 140					no default
rastercolor = '007f80'				default: ffffff (white) 	
rastercolor = 'transparent'			a special value for making the raster (seem) transparent


5. Palette

A palette file can be supplied to limit the number of colors available. Assignment to objects will
still be performed in a random fashion. The pathname supplied must obviously point to an existing,
readable file.

palette = 'yes'				default: no
palettefile = '/home/nobody/palette.txt'	no default

A palette file is expected to contain one hexademimal RGB value per line, which may be followed by
an arbitrary text. This should keep the palette file human-readable. If supplied, it is presumably
a description of the color in question. It is good practice to separate the description the RGB
value by an amount of whitespace, for example:

---------------------------------------------------------
04d9ff          Neon Blue
39ff14          Neon Green
ff073a          Neon Red
cfff04          Neon Yellow
---------------------------------------------------------

Apart from the text following the RGB value, no comments, indentations or empty lines are
expected. These will result in unanticipated colors showing up in the result. No validation of RGB
values is performed, nor of the file content as a whole: the script will simply TRY to read the
first six characters of each line, and will pass anything it finds, including an empty string
retrieved from an empty line, to the list of color codes. If the palette file contains any empty
lines, objects colored black will show up on the screen.

----------------------------------------------------------------------------------------------------
Note: A matrix file has precedence over a palette: make sure that 'matrix' below is disabled if you
are planning to use a palette file.
----------------------------------------------------------------------------------------------------


6. Matrix

Supplying a matrix file allows for full control over the colors rendered. It allows the colors for
every individual cell and eye to be set to a specified value. A neat feature is that it allows the
user to define the color names. These are used in a matrix, present in the same file. The matrix
must follow the color definitions. If no matrix is present, nothing will be shown.

matrix = 'yes'					default: no
matrixfile = '/home/nobody/matrix.txt'	no default

Example matrix file:

---------------------------------------------------------
# Basicolor matrix

# Color values
b = 0000ff
p = 6600ff              # comment
r = ff0000
o = ff6600
y = ffff00
g = 00ff00

        # c1    c2      c3      c4      c5

        o:g     b:r     r:y     g:p     o:y     # r1

        g:p     y:b     o:g     b:g     r:p     # r2

        r:g     p:y     g:r     y:r     g:b     # r3

        o:g     b:r     r:y     g:p     o:y     # r4

        g:p     y:b     o:g     b:g     r:p     # r5

---------------------------------------------------------

Matrix files follow perfectly standard etiquette with regard to comments. Anything preceded by a '#'
is conidered one, and is ignored as such. Empty lines and indentation are tolerated.

A matrix file has two distinct sections:

- first come the code definitions, in the form <name> = <value>
- next the matrix itself, with colors specified as <cellcolor>:<eyecolor>

The names of the color codes (b, p, etc. in the example above) are defined entirely by the user.
The matrix lines above might have also looked like this:

        green:purple     yellow:blue     orange:green  ...etc...

with codes defined as:

blue = 0000ff
purple = 6600ff
etc..

The only restriction with regard to code names, is that thay should not contain whitespace or the
'=' character.

All elements of a <cellcolor>:<eyecolor> must be present. If any of these are missing, difficult to
interpret list errors may occur.

It is up to te user to supply a sane matrix, with correct codes and without any excess rows or
columns. Rasterscript chooses to not anticipate every possible error in the input. The results of
erroneously constructed matrix files may range from the SIS extension exiting with an error message,
or running but with no image appearing on the page, to Inkscape - and perhaps even the computer -
freezing altogether. It is therefore wise to make sure all opened documents are at least in a saved
state before testing a new matrix file.


Conclusion

This script serves no purpose whatsoever. Users are expected to be initially excited with its
displays of colorful randomness, but to quickly get bored and turn their attention to something else.
The only application conveivable, apart from producing sort of 'cool' images, might be to test color
combinations from a an existing palette, or to discover unexpected color combinations in the case of
entirely random colors.

It's fun though, for a while at least.