# Appendix A - Miscellaneous

## A.1 Shortcuts

Several of the menu options have keyboard shortcuts which are labelled next to the option. In addition to these facilities, there are further shortcuts that you may find useful.

### A.1.1 Keyboard Shortcuts

A | Draw open arrow head while drawing line
Q | Quit the program (can be switched off in the preferences window)
S | Draw closed arrow head while drawing line
Insert | Transform the image colours, e.g. gamma, brightness, contrast
Home | Toggle full view mode
Page Up | Scale image
Page Down | Resize canvas
Delete | Crop image to current selection
Escape | Cancel paste or selection, Cancel line drawing
Enter/Return | Commit paste operation
Arrow keys | Painting tool - Move the mouse cursor
Arrow keys | Paste/selection tool - Move area by one pixel
Arrow keys + SHIFT | Nudge mouse pointer, selection box or paste box by x pixels - x is defined by the Preferences window
Arrow keys + CTRL [ + SHIFT ] | Move layer or resize selection box
[ or ] | Change colour A to the next or previous palette item
Shift + [ or ] | Change colour B to the next or previous palette item
+ or = | Main edit window - Zoom in
- | Main edit window - Zoom out
Shift + or = | View window - Zoom in
Shift - | View window - Zoom out
1 | 10% zoom
2 | 25% zoom
3 | 50% zoom
4 | 100% zoom
5 | 400% zoom
6 | 800% zoom
7 | 1200% zoom
8 | 1600% zoom
9 | 2000% zoom
Shift + 1 | Edit image channel
Shift + 2 | Edit alpha channel
Shift + 3 | Edit selection channel
Shift + 4 | Edit mask channel
F4 | Paint tool
F9 | Selection tool

### A.1.2 Mouse Shortcuts

Left button | Paint to canvas using the current tool and pattern
Middle button | Selects the point which will be the centre of the image after the next zoom
Right button | Paint to canvas with A/B colours reversed, Commit paste to canvas / Stop drawing current line / Cancel selection
Scroll Wheel | In GTK+2 the user can have the scroll wheel zoom in or out via the Preferences window
Ctrl+Left button | Choose colour A from under mouse pointer
Ctrl+Middle button | Create colour A/B and dither pattern based on the RGB colour in A (RGB images only)
Ctrl+Right button | Choose colour B from under mouse pointer
Ctrl+Scroll Wheel | Scroll the main edit window left or right
Shift+Right button | Selects the point which will be the centre of the image after the next zoom

You can fixate the X/Y co-ordinates while moving the mouse:

Shift | Constrain mouse movements to a vertical line
Shift+Ctrl | Constrain mouse movements to a horizontal line

## A.2 Supported File Types

mtPaint can handle the following file formats:

Format | Load | Save
BMP | All. | Indexed palette. 24 bit RGB including alpha channel.
GIF | All single images. Animation frames via Gifsicle. | Indexed palette including transparency index. Animations via Gifsicle.
JPEG | All. | 24 bit RGB.
JPEG2000 | All. | 24 bit RGB.
LSS16 (*.lss) | All. | Indexed palette (16 colours), 18 bits per colour (6 per RGB channel).
PNG | All. | Indexed palette. 24 bit RGB. Including transparency index, alpha/selection/mask channels.
TGA | All. | Indexed palette. 24 bit RGB including alpha channel.
TIFF | All. | Indexed palette. 24 bit RGB. Including alpha channel.
XBM | All. | 2 colour indexed palette including hotspot.
XPM | All with 4096 colours or less | Indexed palette. 24 bit RGB images with up to 4096 colours. Including transparency index and hotspot

File types PNG, JPEG, JPEG2000, TIFF, and GIF are handled by external libraries: libpng, libjpeg, libopenjpeg, libtiff, and libungif/giflib. As a result of this, the efficiency of these file operations will depend on the version of these libraries installed on your system. For example, libtiff is unable to read certain old JPEG compressed TIFF files. For more information on these libraries, consult their respective websites:

libpng | http://www.libpng.org/pub/png/libpng.html
libjpeg | http://www.ijg.org/
libopenjpeg | http://www.openjpeg.org/
libtiff | http://www.libtiff.org/
libungif / giflib | http://libungif.sourceforge.net/doc/

### A.2.1 PNG Files

When saving a PNG file you can use the preferences window or the save as dialog to set a compression value between 1 and 9 (0 = no compression). A value of 9 compresses the most, but with the penalty that it will take more CPU usage and time to create the file. Therefore for large images it may be sensible to use a lower value. Faster saving may be very important for certain jobs such as saving the frames of an animation. Here is a table comparing the time it takes me to save a 4096x4096 photo. As a comparison the basic BMP image format is also included:

Format | Seconds to Save | % of PNG 9 | KB file size | % of PNG 9
BMP | 1 | 0.6 | 49,236 | 514.7
PNG 1 | 6 | 3.8 | 13,055 | 136.5
PNG 5 | 10 | 6.4 | 10,656 | 111.4
PNG 9 | 156 |  | 9,566 |

### A.2.2 JPEG 2000 Files

The JPEG file format is currently the most commonly used file format for storing digital photos. However, there also exists a more modern and higher quality format called JPEG 2000 which mtPaint can use. Unfortunately this newer format has yet to be supported by all image viewers (e.g. web browsers) and editors, but it is still an excellent choice for storing images when quality is the most important factor.

There are two main benefits of JPEG 2000 files (JP2) compared to a regular JPEG file:

- For the same file size, JP2 files are normally of a higher quality.
- Photos can be stored losslessly so that no information is lost.

  #### A.2.2.1 Lossy Image Comparison - JPEG vs JP2

  In this example I have used the photo image from section 6.8.3, and then saved it as a JPEG image at level 95, and compared this to a JPEG 2000 file saved at level 6. The JPEG file was 15,172 bytes in size, with the JP2 file being 14,438 bytes.

  Pixel by pixel analysis of the difference between the original image and the compressed files reveals the following errors:

  | Channel | JP2 (6) | JPEG (95)
  Maximum Error | Red Green Blue | 19 12 21 | 84 46 104
  Average Error | Red Green Blue | 2.78 1.87 2.62 | 4.17 2.54 5.15

  This data was created by using the micmp program from libmtpixel, available from the mtPaint website.

  In this example, the JP2 image on the left shows far closer similarity to the original in the centre than the JPEG on the right. The JPEG wheel arch at the top is much more blurred and has completely lost its light rim.

  In this example, the roof of the red car appears to be a different shade on the JPEG image at the bottom compared to the original in the centre, and the JP2 image at the top.

  #### A.2.2.2 Lossless Image Comparison - PNG vs JP2

  To store a photographic image losslessly it is possible to use a compressed PNG file. However, for most photos the JP2 format produces smaller files by about 5-25%. As an example, here are the results for the photo image in section 6.8.3:

  Format | File Size (Bytes)
  Uncompressed BMP | 87,222
  Lossless PNG (level 9) | 56,297
  Lossless JP2 (level 1) | 51,731

  It should be noted that the PNG file format still produces smaller files than JP2 when compressing images with fewer colours, such as pixel art, so the benefits are strictly limited to photographic images.

  ## A.3 Grabbing Screenshots

  mtPaint can be used to grab a screenshot with either 'File->New' or using 'mtpaint -s' from the command line. If you are an IceWM user you can assign the key 'Print Screen' to grab a screenshot by editing the file ~/.icewm/keys to include:

  key "Print" mtpaint -s

  ## A.4 Preferences

  The preferences you choose in the preferences window are stored in the file ~/.mtpaint on GNU/Linux systems and on the root of the drive you are using in Windows, such as C:

  ### A.4.1 Touch Sensitive Tablets

  It is possible to use the Preferences window to enable the use of touch sensitive tablets in mtPaint. Firstly, these devices need to be set up and tested using your operating system drivers. Once you have done this, you can then configure the 'Tablet' section of the Preferences window in order to affect tool size, flow and opacity. To test if this is working, use the tablet to apply pressure to the test area and you will see how much pressure has been registered.

  ### A.4.2 Localized Translations

  mtPaint can be compiled to use localized translations to help non English speaking people. If your copy of mtPaint has this feature, there will be a section of the Preferences window called 'Language' which you can use to choose a different language.

  Each of these translations has been completed voluntarily by several mtPaint users who wish to make its features more accessible. Some of these translations are not complete. If you wish to complete any of these translations, or create new translations then you are advised to visit the mtPaint website so you can contact the maintainer in order to get instructions on doing this.

  ## A.5 Limitations

  The maximum image geometry is 16384x16384. The minimum geometry is 1x1.

  After loading a new palette, the canvas may contain references to colours that are not defined. I call these orphan pixels. If you examine the image information via the Image menu you will see how many pixels have been orphaned. You can retrieve the pixels by expanding the palette to 256 items and then 'Palette->Remove Unused Colours'.

  When using the colour A/B editor with an indexed image, if colour A = colour B, you must edit colour B to change its RGB.

  On some systems there are problems when editing large images at high zoom levels like 2048x2048 at 1600%.

  Some key combinations may not work under certain window managers, e.g. Shift+F1-F12 or Ctrl+Mouse button.

  Using the status bar items 'Cursor X,Y' and 'Pixel [I] {RGB}' can cause high CPU usage on older hardware when moving the cursor vigorously.

  The maximum number of layers is 100.

  Text rotation does not work in Windows ME/95.

  The polygon line selection in Windows is not as clear as the GNU/Linux version.

  ## A.6 Customizing mtPaint

  One of the benefits of free software is that you have access to the source code so you can customize the program to suit your needs.

  ### A.6.1 Creating Patterns

  Each pattern is simply an 8x8 grid which you can edit in the source code file ./src/icons1/xbm_patterns.xbm. To use these new patterns you need to save the new file somewhere safe and then refer to this file in the Path section of the Preferences window.

  ### A.6.2 Creating Brushes

  If you have a particular preference for certain types of brushes, such as circles or sprays, you can manually edit the sources to cater for your needs. Edit memory.c and find mem_brush_list which defines all of the brushes. Each entry is defined by a tool type, tool size and flow.

  ### A.6.3 Custom Icons

  The directory ./src/icons1 contains icons and mouse pointers that are compiled into mtPaint. It is possible to create custom icon sets to suit personal taste. For example in order to create and build a new set try:

  - cd src
  - cp -r icons1 icons-new
  - Edit the icons and pointers in icons-new as required
  - ./configure icons-new
  - make

  ## A.7 File Actions

  The 'Actions' section of the File menu can be used to send the current image file to another program, such as a web browser or email client. The implementatation varies between GNU/Linux and Windows systems due to the different underlying system structures. In both cases though you can configure up to 25 items, with each having a text description (Action), a command and a directory in which the command will be run. The first 15 items will be placed in the menu as presets. If you don't want an item to appear as a preset then you can place a '#' character at the beginning of the Action. You can re-order the items in the list by dragging and dropping them in the list.

  When editing the command, the current image file is represented by using '%f' which is substituted when the command is run.

  ### A.7.1 GNU/Linux Systems

  The GNU/Linux version of mtPaint comes pre-loaded with some examples of file actions. The command is executed using the shell command sh, so in the case of bash you can using more than one command by separating them with a semi colon. For example this command waits for 5 seconds and then grabs a screenshot:

  sleep 5; mtpaint -s &

  Because commands are run through the shell you can use any shell facilities like pipes, redirection, and wildcards.

  ### A.7.2 Windows Systems

  To run a program using the Windows version of mtPaint you must place the whole path of the program in the command box. For example the following command starts MS Paint editing the current image (in Windows XP or Window 98 respectively):

  C:\WINDOWS\system32\mspaint.exe %f

  C:\Program Files\Accessories\MSPAINT.EXE %f

  ## A.8 Installing mtPaint as a Library (libmtpaint)

  From version 3.20 of mtPaint it is possible to install the program as a library and allow C programs to use mtPaint's facilities. Naturally this is only an option for C developers and not unskilled users.

  There are many reasons why a developer may want to use mtPaint's facilities, such as: the creation of animation frames, bulk conversion of files from one type to another, image analysis, etc.

  ### A.8.1 Compilation and Installation

  These steps will install static and dynamic libraries to /usr/lib, and also place the mtpaint.h header file into /usr/include :

  ./configure api
  cd src
  make libs
  su -c "make libinstall"

  ### A.8.2 Usage

  Using libmtpaint is very similar to using any other C library. In the source code you must use this directive:

  #include <mtpaint.h>

  The following code is then required to initialise GTK+ and mtPaint:

  gtk_init( &argc, &argv );
  mtpaint_mem_init();
  mtpaint_window_init();

  You then write your own code for the program. If the program is intended to be run interactively, you will need to pass control to GTK+ like this:

  gtk_main();

  Lastly you will need to close mtPaint just before the program ends:

  mtpaint_quit();

  In order to link the program to libmtpaint, you will need to add the compiler option -lmtpaint. Naturally you will also have to link against GTK+ and the other C libraries that you use.

  ### A.8.3 Examples

  The easiest way to see how all of these things work is to click HERE and download some example code. This includes a Makefile and C source code which builds an interactive example to demonstrate painting and file operations. Here is a screenshot:

  The most sophisticated example here is the creation of GIF animation frames which are then knitted together using Gifsicle. Here is the resulting animation: