picedit.doc

This document describes the picture editor of Free Hero Mesh.

To start the picture editor, use the -p switch. In this case, the puzzle
set files are not required to exist; the .xclass file will be created if
necessary, and the other ones are ignored.

This allows creating the graphics for the classes of objects in the puzzle
set. The class definition file will associate one or more pictures with
each class, using the names given in the picture file.

Each named picture can have up to fifteen variants. Only one variant is
used; which one is used depends on the .altImage and .imageSize settings,
which can be defined by the end user.


=== Main menu ===

The main menu displays the list of the names of all pictures. This list is
sorted by name. Grey means a normal picture, green means dependent, and
brown with a red plus sign in front means multidepenent.

You can push escape to quit and save, or shift+escape quits without saving.

The F1 key adds a picture.

The F2 key deletes a picture by name.

The F3 key allows entering a name of a picture to edit.

The F4 key renames a picture.

The F5 key adds a dependent picture (see the below section).

The F6 key is used to set configuration. Currently, this only sets the
default picture sizes. If you specify zero, then it will use the user
configuration, otherwise it is saved with the puzzle set, and will be
used when adding new pictures. You can specify multiple sizes; it will
create it with variants of all of those sizes. You can also specify the
same numbers multiple times if you want multiple variants of that size.

The F7 key copies a picture.

The F12 key allows entering a SQL statement. If there are any result rows,
only the first row and first column are displayed.

Any of the prompts for picture names can start the picture name with a
plus sign in order to affect a multidependent picture; see the below
section about multidependent pictures for details.


=== Drawing ===

The following keyboard commands are available:

Esc
  Leave the drawing screen.

Shift+Tab or [
  Select the previous image variant.

Tab or ]
  Select the next image variant.

1 to 9
  Select one of the first nine image variants.

Space
  Unmark the block and point.

Return
  Copy the marked part of the picture to the clipboard. This will discard
  the previous contents of the clipboard (if any). This is separate from
  the operating system clipboard; it is local to Free Hero Mesh, and is
  lost when Free Hero Mesh is restarted.

Insert
  Paste from the clipboard. If a block is marked, it will stretch the
  pasted image to fit the area. If a point is marked but not a block, that
  point will be the upper left corner of the paste position. If neither,
  then it is pasted with its upper left corner at the upper left corner of
  the current image buffer.

Delete
  Erase the pixels marked block, making all of the pixels transparent.

Arrows
  Allows selecting a colour without using the mouse.

Home
  Selects transparency as the current colour.

F1
  Rotate marked area clockwise by 90 degrees. The marked area must be
  square in order for this to work.

F2
  Rotate marked area counterclockwise by 90 degrees. The marked area must
  be square in order for this to work.

F3
  Flip marked area vertically.

F4
  Flip marked area horizontally.

F5
  Resizes the current image variant. It will ask for the size; enter a
  number from 1 to 255 to set the size (which is always square), and then
  it will resize and clear the image. If you enter P then it will become
  a copy of the contents of the clipboard; this won't work if the contents
  of the clipboard is not square.

F6
  Add a new image variant. It will ask for the size, like with F5, except
  this adds a new one rather than replacing the existing one. The maximum
  number of image variants is fifteen.

F7
  Delete the current image variant. You cannot delete all of the variants
  of an image; you must have at least one.

F8 or number pad *
  Mark the entire image as a block.

F9
  Import a picture. At the prompt, you must enter a system command which
  will produce a square farbfeld picture on stdout. The imported picture
  will replace the current picture variant.

F10
  Export a picture. At the prompt, you must enter a system command which
  will read a farbfeld picture from stdin.

F12
  Enter a SQL statement to edit the current picture. This should be a
  UPDATE statement which updates the column called "C" of the table called
  "GRAPH". It has columns "X" and "Y" which are the coordinates of the
  pixel, and "C" which is the colour of the pixel. It may also be a SELECT
  statement in order to query it, and the response is then displayed
  (which must be a single row and single column only). This table also has
  a column "S" which is the same for all rows, and is the size of the
  picture, which can be used in macros (see config.doc).

` or =
  Exchange the current picture with the spare page. (The spare page is not
  stored in the puzzle set; it is lost when Free Hero Mesh is terminated.)

Click in the colour palette on the right to select a colour. With the left
button, that colour is selected as the current colour. The middle button
will replace everything of the current colour with the clicked colour, and
the right button will exchange pixels between the current colour and the
clicked colour; in either case, if any block is marked, only the marked
block will be affected.

You can type alphabets to select the drawing mode. The available drawing
modes are as follows:

Draw (D)
  The left mouse button draws with the current colour, and the right mouse
  button draws transparent pixels; you can also hold and drag the mouse to
  draw multiple pixels. Clicking with the middle button will select the
  clicked colour as the current colour.

Mark (M)
  Select a point with the left button, and then the right button selects
  the opposite corner of the rectangular area to mark.

Pick (P)
  Clicking in the picture editing area will have the same effect as
  clicking in the colour palette, on the same colour as the pixel.

Line (L)
  Click the left button on the initial point of the line, and then click
  the middle or right button on the final point of the line. If the right
  button is used then the new point is the new initial point for further
  lines, otherwise a further line will use the old initial point.

Hollow rectangle (R)
  Click the left button on the first corner and the right button on the
  other corner.

Filled rectangle (F)
  Click the left button on the first corner and the right button on the
  other corner.

Hollow circle (C)
  Click the left button at the centre of the circle and the right button
  at the radius, or you can click the left button at the radius and the
  middle button at the centre.

Filled circle (I)
  Click the left button at the centre of the circle and the right button
  at the radius, or you can click the left button at the radius and the
  middle button at the centre.

Hollow ellipse (E)
  Click the left button on one corner of the bounding rectangle of the
  ellipse, and then click the middle or right button on the other side.

Filled ellipse (S)
  Click the left button on one corner of the bounding rectangle of the
  ellipse, and then click the middle or right button on the other side.

Flood (O)
  Click any button to flood an area of a solid colour with the current
  colour. Which button decides the directions to use, where the left
  button means the von Neumann neighbourhood and the right button means
  the Moore neighbourhood.

For clicking in the palette or the Pick mode, with the middle or right
mouse button, you can also push CTRL or SHIFT keys with it in order to
affect only odd or only even coordinates.


=== Dependent pictures ===

A dependent picture depends on one or more independent pictures. It
consists of any combination of the following items, in any order:

* Base: This one must come first, and is the independent picture which
will be used as the base; all other filters are applied to alter it.

* Flip/rotation: Flip/rotate the picture. "Identity" also belongs to this
category, but has no effect.

* Replace colours: A list of pairs of colours. The first of each pair is
the old colour, and next the colour to replace it with.

* Advance colours: A list of colours; change each colour mentioned in the
list into the next colour in the list after that one.

* Exchange colours: A list of pairs of colours; each colour is changed to
the other colour in the pair.

* Overlay: Paste the specified independent picture over the current
picture, showing through wherever it is transparent.

* Shift: Shift the picture. Specify the sizes and shift amounts in the
format "size: shift"; each size also affects all multiples of that size,
in which case the shift amount is also multiplied by the same amount.

* Hue/Shade: Specify hue adjustment and shade adjustment. The hue
adjustment is unsigned, and the shade adjustment is signed; any colours
that are in range 1 to 225 are affected; other colours remain unchanged.


=== Multidependent pictures ===

A multidependent picture lump defines several pictures which are formed
from one or more independent pictures and filters, using common sets of
base pictures and filter chains.

You can define a list of up to 63 bases and up to three lists of filter
chains each of which may contain up to 63 filter chains; all pictures are
generated which take all combinations of one item from each list.

Each list may be nullable. In this case, you can omit to choose an item
from that list for forming a picture. Empty lists are automatically
nullable, even if they have not been defined as nullable.

Each picture is made from a base, followed by a filter chain in the first
list, and then the second list, and then the third.

The bases are names of independent pictures. The filter chains may have
any names, up to seven characters; if the first character is a dot or
underscore or hyphen, then they may be up to eight characters. The name
of the resulting picture is then the name of the selected item of each
list, in order, concatenated together (the name of the multidependent
picture lump itself is not used).

Each filter chain is defined in the same way as for dependent pictures,
although you cannot specify a base name, because there isn't any.