
_____________________

Translator user guide
_____________________


User, please note
=================

Translator is Shareware. It is not free software. You may, however, freely use
it for a 30 day trial period. After this trial period, you must decide whether
or not you want to continue using it. If you do, you must register your copy of
Translator (refer to 'Registering' for details). If you don't, you must delete
your copy of Translator and can never use it or try it out again.

Please respect the rules of Shareware. Shareware is a 'try before you buy'
method of distribution that provides you with excellent software at a very low
price. Programs like Translator have cost an awful lot of time and effort to
develop, will serve you well for a long time, and will cost you very little
money (well below what is reasonable in a commercial sense).

Copyright notice
================

The copyrights (c) of this program belong to John Kortink. All rights are
reserved.

You may not make changes to this program (except for documented configuration
changes). If you distribute it, you may only distribute the complete and
unchanged original copy (as you first received it). You may distribute this
program freely, but must obtain written permission from me if it is to be
distributed as part of, or alongside, any product that is meant to generate
profits. This program is provided 'as is'. Fitness of this program for any
particular purpose is not implied. Using it is entirely at your own risk.


//
//
// Introduction
//
//

Translator is a bitmap image viewer, processor and convertor.

It is able to read and write a wide variety of bitmap image formats, while also
providing a useful set of processing functions with which these images may be
enhanced and/or manipulated, and batch-processed. Translator uses sophisticated
algorithms to ensure high quality results.

In addition to this, you will find Translator to be *fast*. Most of Translator
has been written in ARM assembly code, the rest has been written in C++. In
addition, some ported C code is used for JPEG and PNG conversion.


//
//
// Compatibility
//
//

Translator should be compatible with :

- RISC OS 3.1 and later
- ARM 2 and later processors (26-bit architectures only)


//
//
// The major leap
//
//

If you have used Translator versions before 8.00, you will no doubt notice that
the program has been enhanced in a very big way.

In fact, I rewrote all of it, and the result is version 8.00. Most of the
features of the 'old' Translator have been retained, and most of the features
of Creator and GreyEdit, my two other image processing programs, were added.

And there are some major additional enhancements, among which :

- RISC PC compatibility
- The ability to function as an editor
- The ability to load multiple images
- Automatic 'virtual memory'
- Support for selections
- Proper 'interpolating' upscale
- Proper 'averaging' downscale
- Batch processing


//
//
// Using Translator
//
//

On Translator's iconbar menu the usual 'Info' and 'Quit' icons can be found.

In addition, 'Do others' invokes batch processing (refer to its discussion
elsewhere), 'Options...' gives access to the 'Options' window and 'Choices'
gives access to the 'Choices' menu. Both the 'Options' window and the 'Choices'
menu are described below.


//
//
// Loading an image
//
//

There are three ways to load an image :

1. Drag the image file to Translator's icon.

Translator will complain if it cannot recognize the image format.

2. Double-click on the image file while Translator is loaded.

The file must have a file type recognized by Translator. If Translator cannot
recognize the image format (i.e. the file probably has a wrong file type), it
will not complain. This is so that other applications may be offered a chance
to load the file.

3. Double-click on the image file while Translator is not loaded, but has
   been 'seen' by the RISC OS Filer.

This will only work for image formats that have an allocated filetype. Image
formats that can only be recognized by some form of signature in the image file
won't load in this way (you will have to use method 1 or 2 instead). When you
use method 3, Translator will be loaded automatically, and will subsequently
load the image.

The image will appear in an 'image window'. The 'image window' is described
below. You may load multiple images, subject to hard disc space limitations.
Refer to 'Image storage' for more details.


//
//
// Image storage
//
//

Translator does not limit the size or number of the images you can work with.
It can store images either in memory or in a file. An image stored in memory is
referred to as 'cached', an image stored in a file as 'uncached'.

By default, Translator chooses to cache images if enough memory is available to
do so. Otherwise, it will automatically uncache the image. Alternatively, you
can tell Translator never to cache images. This may be useful when memory is
tight. Refer to the discussion of the 'Image cache' and 'Display cache' parts
of the 'Options' window.

If you wish, you can subsequently cache or uncache images on an individual
basis. This is provided by the 'Cache' entry of the image window menu (refer to
its discussion elsewhere). Once an image is uncached it is never re-cached
automatically. However, a cached image may become uncached automatically, e.g.
when the image is scaled up and there is not enough memory left to store the
new, bigger image.

Translator needs to store the image twice. One copy is the actual image data,
the other is needed solely for the image display. Both the image data and the
image display have their own seperate cache settings.

In general, when an image is cached, it can be processed much quicker than when
it is uncached. Usually, keeping the image display uncached does not slow down
processing as much as keeping the image data uncached, so if memory is tight
and you have to choose, uncache the image display before you uncache the image
data.

Of course, if you regularly need to process reasonably large images and memory
is tight, the best move is to invest in more memory. It comes very cheap
nowadays. However, as Translator can also store images in files, the size of
your harddisc will eventually be the only factor limiting the size and number
of images you can process.


//
//
// The image window
//
//

The image window displays the image. Translator uses sophisticated algorithms
to maximize the quality of the display given the limitations of the selected
screen mode. It is recommended to use a 16- or 32-bit screen mode (i.e. a '32
thousand' or '16 million' colour mode).

The filename under which the image was last saved appears in the title of the
image window (for an as yet usaved image this is the original filename). The
filename is followed by the number that Translator assigned to the image (this
number has no real significance, but reappears in some dialogue windows, so you
can tell which image is being referred to). If the image has been edited and
not subsequently saved, a '*' appears behind the image's filename.

Clicking the 'close' icon of an image window will delete the image. If you
attempt to delete a modified image, Translator will warn you. You can switch
off this warning if you wish. Refer to the discussion of the 'Miscellaneous'
part of the 'Options' window for more details.


//
//
// Making a selection
//
//

You may select a part of the image by 'dragging a box'. This part will be
referred to as 'the selection' in the rest of this document.

First click and hold SELECT on a corner point, then drag towards the opposite
corner and release SELECT. Clicking SELECT again will remove the selection.
Clicking and/or dragging ADJUST will modify the existing selection.

Most of the available image processing functions affect either the selection or
the whole image (if there is no selection). A few image processing functions
always affect the whole image, ignoring the selection (if any), e.g. scaling
and rotation.

Position and size of the selection may be monitored. Refer to the discussion of
the 'Selection' entry of the image window menu.


//
//
// The image window menu
//
//

Clicking MENU on the image window will pop up a menu that provides image
processing functions and information :

==========
= Origin =
==========

This leads to a window showing information relating to the image when it was
first loaded.

========
= Save =
========

This leads to the 'Save image' window, which allows you to save the image in a
variety of image formats.

Clicking on the window will make it permanent. Note that the title of this
window carries the image number which also appears in the title of the
corresponding image window.

The format of the output image may be chosen as follows :

- 'Format' allows you to choose the image format.
- 'Colours' allows you to specify the number of colours to be retained in the
  image, by bits per pixel (the number of colours is '2 ^ bits per pixel'). The
  choices presented depend on the chosen image format. If the writable field to
  the right of the menu icon is not shaded, you may also specify a more precise
  number of colours if you wish.
- 'Compression' allows you to choose the compression method used. The choices
  presented depend on the chosen image format.
- 'Filename' allows you to specify the leafname or the full pathname of the
  image to be saved.

The 'Colours' field deserves some further explanation. This is displayed as 'x
bit r:g:b type', where 'x' is the number of bits per pixel (referred to below
as 'bpp'), 'r', 'g', and 'b' are the number of bits of accuracy in a pixel
colour of red, green, and blue respectively, and 'type' is the pixel colour
type. There are essentially two pixel colour types :

- The 'palette' or 'grey' type indicates that pixel values are not pixel
  colours themselves but indices into a pixel colour lookup table (called a
  'palette'). The 'grey' pixel type also indicates that all palette colours are
  shades of grey. If 'fixed' appears in the type, the palette is always fixed
  (in all other cases Translator calculates an optimal palette).
- The 'true' pixel type indicates that pixel values directly represent pixel
  colours. Therefore, 'x' is always the addition of 'r', 'g' and 'b'.

Saving the image may or may not need colour quantization, colour dithering
and/or colour remapping algorithms to be applied. Translator applies the
required algorithms automatically. The accuracy of the calculations performed
by the algorithms may be changed, if needed. Refer to the discussion of the
'Quantization' and 'Dithering' parts of the 'Options' window.

Colour quantization is used whenever a 'superset' of colours (used in the input
image) needs to be reduced to a smaller 'subset' of colours (to be used in the
output image). The colour quantization algorithm calculates the subset of
colours that best represents the superset of colours. Colour quantization is
only used for palette colour output images. The colour quantization algorithm
used is known as 'Heckbert median cut'.

Colour dithering is used when the number of colours in the output image is less
than that in the input image, or when any of the number of bits per r/g/b in
the output image colours is less than that in the input image colours, or when
the output palette is fixed. In all these cases, some or all of the input image
colours do not have an exactly matching colour in the output image, and so, for
these colours, the 'closest' output image colour is used. Per pixel, the colour
dithering algorithm then 'diffuses' the error (the difference in colour) by
slightly changing the colours of neighboring pixels. This makes the errors less
visible to the human eye. The colour dithering algorithm used is a 'zizag'
variant of the widely known and used Floyd-Steinberg algorithm.

Colour remapping is used whenever the colour quantization algorithm is used,
and it finds that the number of different colours actually used in the input
image is less than or equal to the number of available output image colours.
In this case, the output image palette simply consists of all actually used
input image colours, and all that is needed is 'remapping' of the input image
colours to their respective output image colours. An exact copy of the input
image results. For example, it is not uncommon to encounter 24 bpp 'true
colour' image files in which only 256 colours (or even less) are actually used.
This can happen if someone, somewhere, sometime, for whatever dim reason, has
'promoted' an 8 bpp palette colour image to 'true colour'. In these cases, the
original palette colour image is exactly recreated, usually saving space.

Translator does the right thing if the output palette turns out to be all grey
(which usually only happens when the output format requires a fixed grey
palette, e.g. PBMPlus 8 bpp or JPEG 8 bpp). In this situation, the colour
dithering algorithm used is unsuitable if the input image is in colour, because
colours are impossible to approximate well with just grey values, resulting in
a bad quality output image. A special 'grey only' dithering algorithm is used
instead, which gives much better results. The 'Dithering' setting in the
'Options' window has no effect if this algorithm is used.

After making all your choices, you can save the image by either dragging the
filetype icon, or by clicking on the 'Save' icon. Dragging the filetype icon
will result in the image being saved to the directory that the icon was dragged
to, using the leafname specified under 'Filename'. Clicking on the 'Save' icon
will result in the image being saved to the pathname specified under
'Filename'. This is the original pathname by default.

Clicking 'Cancel' will cancel the save.

=============
= Transform =
=============

This leads to a submenu containing 'transformation' functions (i.e. functions
that move pixels around, leaving their colours unchanged).

=======================
= Transform -> Mirror =
=======================

This leads to a submenu containing 'mirror' functions.

Clicking 'Horizontal' or 'Vertical' will mirror the image in horizontal or
vertical direction respectively.

=======================
= Transform -> Rotate =
=======================

This leads to a submenu containing 'rotate' functions.

Clicking '-90 degrees', '+90 degrees' or '180 degrees' will rotate the image by
the specified angle.

The selection is ignored (except for rotation by 180 degrees, which is really a
'Mirror Vertical' followed by a 'Mirror Horizontal').

======================
= Transform -> Scale =
======================

Clicking on this menu entry will scale the image.

The selection is ignored.

The scaling ratio can be set seperately for X (width) and Y (height). The
'arrow' icon can be clicked to toggle between 'connected' mode (normal arrow)
and 'unconnected' mode (red cross through arrow). In 'connected' mode, the X
and Y ratios will change together. In 'unconnected' mode, they can be changed
seperately.

If you need to scale the width and/or height to a fixed number of pixels
(regardless of the current size of the image), you can specify 'x' (or 'X') and
'y' (or 'Y') respectively as the ratio divisor, and the required number of
pixels as the ratio multiplier.

Note that Translator uses accurate 'interpolating' (scaling up) and 'averaging'
(scaling down) algorithms, giving a very good quality result.

=====================
= Transform -> Crop =
=====================

Clicking on this menu entry will crop the image, leaving only the pixels
belonging to the selection.

===========
= Process =
===========

This leads to a submenu containing 'processing' functions (i.e. functions that
recalculate pixels' colours, leaving their position unchanged).

=====================
= Process -> Filter =
=====================

This leads to a submenu containing 'filter' functions. A filter function looks
at every pixel in turn, and recalculates its colour, considering the old colour
of the pixel and the colours of every one of its eight neighbor pixels (i.e.
the pixels to the 'north', 'south', 'east', 'west', 'north-east', 'north-west',
'south-east' and 'south-west'). An alternative way of looking at this is by
imagining a 3x3 pixel window moving over the original image, in which the
middle pixel's colour is replaced by the result of a calculation involving the
colours of all the nine pixels in the window (replacing, however, does not
occur until the calculations have been performed for all image pixels).

Note that some 'neighbors' of pixels at the edge of the image are not available
(for example, the top left pixel has only 'east', 'south' and 'south-east'
neighbors). In these cases, any missing neighbor pixel is assumed to have the
colour of the (in position) nearest image pixel.

Note that the red, green and blue colour components of the pixels are filtered
independently.

Most filters take the pixels in the 3x3 pixel window, multiply their colour
component values by a factor which is different depending on the position of
the pixel in the 3x3 pixel window, and accumulate the resulting values. This
value is subsequently divided by the total of the multiplication factors,
yielding the new colour component value. The set of multipliers is usually
refferred to as a 'kernel'. One of the filter functions allows you to specify
your own kernel.

=============================
= Process -> Filter -> Blur =
=============================

These filters all have a 'blurring' effect.

Kernels of blurring filters generally consist entirely of positive factors.
This has an 'averaging' effect (the new pixel colour is the 'weighted average'
of the colours of the pixels in the pixel window).

You might like to try making your own blurring filters with the custom filter
(described elsewhere). A few tips :

- The lower the 'middle' factor, the stronger the blurring effect is.
- Keep the eight neighbor factors the same for a uniform effect.
- For a 'direction sensitive' blurring effect, use consistently higher factors
  on one 'side' of the kernel compared to the opposite 'side'.

========================================
= Process -> Filter -> Blur -> Average =
========================================

This uses a kernel of :

 1 1 1
 1 1 1
 1 1 1

======================================
= Process -> Filter -> Blur -> Gauss =
======================================

This uses a kernel of :

 1 2 1
 2 4 2
 1 2 1

================================
= Process -> Filter -> Sharpen =
================================

These filters all have a 'sharpening' effect.

Kernels of sharpening filters generally consist entirely of negative factors,
except for the middle factor, which is positive. The factors must add up to a
total of 1 or higher.

You might like to try making your own sharpening filters with the custom filter
(described elsewhere). A few tips :

- The lower the 'middle' factor, the stronger the sharpening effect is.
- Keep the eight neighbor factors the same for a uniform effect.
- For a 'direction sensitive' sharpening effect, use consistently higher
  factors on one 'side' of the kernel compared to the opposite 'side'.

================================================
= Process -> Filter -> Sharpen -> Sharpen weak =
================================================

This uses a kernel of :

 -1 -1 -1
 -1 24 -1
 -1 -1 -1

==================================================
= Process -> Filter -> Sharpen -> Sharpen strong =
==================================================

This uses a kernel of :

 -1 -1 -1
 -1 16 -1
 -1 -1 -1

===========================================
= Process -> Filter -> Sharpen -> Laplace =
===========================================

This uses a kernel of :

  0 -1  0
 -1  5 -1
  0 -1  0

=======================================
= Process -> Filter -> Sharpen -> Lee =
=======================================

This does not use a kernel but a formula :

'The new value is the maximum value in the window or the minimum value in the
window, whichever differs least from the value of the middle'.

==============================
= Process -> Filter -> Noise =
==============================

These filters all have a 'noise removal' effect. They don't use kernels.

============================================
= Process -> Filter -> Noise -> Noise weak =
============================================

This does not use a kernel but a formula :

'If and only if west is equal to east, then the new value is west'.

==============================================
= Process -> Filter -> Noise -> Noise strong =
==============================================

This does not use a kernel but a formula :

'If and only if the maximum of north, west, middle, east and south is equal to
the middle (and only the middle), or the minimum of north, west, middle, east
and south is equal to the middle (and only the middle), then the new value is
the average of north, west, east and south'.

==============================
= Process -> Filter -> Other =
==============================

These filters are useful for 'effects'.

=========================================
= Process -> Filter -> Other -> Maximum =
=========================================

This does not use a kernel but a formula :

'The new value is the maximum value in the window'.

=========================================
= Process -> Filter -> Other -> Minimum =
=========================================

This does not use a kernel but a formula :

'The new value is the minimum value in the window'.

==========================================
= Process -> Filter -> Other -> Sobel X+ =
==========================================

This uses a kernel of :

 -1 0 1
 -2 0 2
 -1 0 1

Note that 127 is added to the accumulated value before division because the
total multiplication factor is 0.

==========================================
= Process -> Filter -> Other -> Sobel X- =
==========================================

This uses a kernel of :

 1 0 -1
 2 0 -2
 1 0 -1

Comments as for 'Sobel X+'.

==========================================
= Process -> Filter -> Other -> Sobel Y+ =
==========================================

This uses a kernel of :

 -1 -2 -1
  0  0  0
  1  2  1

Comments as for 'Sobel X+'.

==========================================
= Process -> Filter -> Other -> Sobel Y- =
==========================================

This uses a kernel of :

  1  2  1
  0  0  0
 -1 -2 -1

Comments as for 'Sobel X+'.

========================================
= Process -> Filter -> Other -> Custom =
========================================

Clicking on this menu entry will apply the custom filter.

In the window that this menu entry leads to, you can enter your own kernel.

Note that the total of the kernel factors should be 0 or higher. The +127
correction factor for a total kernel factor of 0 is applied automatically.

===================
= Process -> Mask =
===================

Clicking on this menu entry will perform a bit masking operation.

In the window that this menu entry leads to, you can specify a bit mask to be
applied to the red, green and blue colour components of the image pixels. If a
mask bit is 0, the corresponding bit of the (8-bit) colour component is forced
to 0, else (i.e. if the mask bit is 1) the corresponding bit is not changed.

The bit mask can be set seperately for the red, green and blue colour
components. The 'arrow' icon can be clicked to toggle between 'connected' mode
(normal arrow) and 'unconnected' mode (two red crosses through arrow). In
'connected' mode, the red, green and blue masks will change together. In
'unconnected' mode, they can be changed seperately.

The bit masking function may be useful when an image has 'noise' in its lowest
colour component bits (e.g. when the image was produced by a scanner or
digitizer with less than 8 bits of resolution per colour component).

============================
= Process -> Correct black =
============================

Clicking on this menu entry will perform a black correction on the image, i.e.
the black level of the image is shifted 'up' or 'down'.

You can enter the correction factor (which may be between -255 and +255) in the
writable icon.

The black correction function may be useful when what should be black in the
image is actually a shade of grey.

============================
= Process -> Correct gamma =
============================

Clicking on this menu entry will perform a gamma correction on the image.

Gamma correction is needed when the original image was scanned or digitized
using a linear scale of intensity values. This has to be corrected for display
on monitors, as monitor tubes do not respond linearly to linear increases in
intensity values. Gamma correction applies the 'inverse' response function of
the monitor tube, so the scanned or digitized image looks more like the
original.

Note that, usually, the only images that may need gamma correction are the ones
that you have scanned or digitized yourself. Even then, it is likely that your
scanning or digitizing software has already applied gamma correction. It is
inadvisable to apply gamma correction to an already gamma-corrected image.
Therefore, most users will not need to use this function.

You can enter the correction factor (something between 1.5 and 2.5 is usually a
good choice) in the writable icon.

========================
= Process -> Make grey =
========================

Clicking on this menu entry will turn all colours into corresponding shades of
grey.

===========================
= Process -> Expand range =
===========================

Clicking on this menu entry will improve the contrast of the image.

This function determines the range of intensity values used in the image and,
if possible, remaps the intensity values to maximize that range.

=======================
= Process -> Equalize =
=======================

Clicking on this menu entry will perform 'histogram equalization' on the image.

Histogram equalization measures the accumulated frequencies of all intensity
values used in the image. The intensity values are subsequently remapped so
that the new frequency graph more closely resembles a straight line.

Note that histogram equalization does not necessarily improve an image's
quality. The effect depends greatly on the image contents.

=====================
= Process -> Invert =
=====================

Clicking on this menu entry will 'invert' the image.

The result is a 'negative' image (i.e. inverting twice results in the original
image).

=========
= Cache =
=========

This leads to a submenu enabling you to cache or uncache the image data or the
image display.

A 'tick' indicates that the image is currently cached. Clicking on the 'Image'
or 'Display' icon will uncache a cached image or vice versa.

Refer to 'Image storage' for more detailed information.

=============
= Selection =
=============

This leads to the 'Selection info' window, which shows the position and size of
the selection.

Clicking on the window will make it permanent. Note that the title of this
window carries the image number which also appears in the title of the
corresponding image window.

========
= Copy =
========

Clicking on this menu entry makes a copy of the image.


//
//
// The 'Options' window
//
//

In this window, you will find seven parts, called 'Load options', 'Save
options', 'Image cache', 'Display cache', 'Miscellaneous', 'Quantization' and
'Dithering'.

The 'Load options' part allows you to specify 'load options' for some image
formats, which influence the way images are loaded. In most cases load options
can be left at their default settings. Refer to 'Supported image formats
(detailed)' for information on specific load options.

The 'Save options' part is similar to the 'Load options' part, except that
these options influence the way that images are saved.

The 'Image cache' and 'Display cache' parts allow you to force Translator never
to cache either the image data or image display respectively. In the 'Auto'
setting Translator will decide automatically whether to cache or not. In the
'Never' setting, Translator will never cache. Refer to 'Image storage' for more
detailed information.

The 'Miscellaneous' part allows you to switch off the warnings about unsaved
modified images, if these annoy you. These warnings are given when Translator
finds you are about to discard an edited but unsaved image.

The 'Quantization' part allows you to select the accuracy with which colour
frequencies are determined during colour quantization (refer to the discussion
of 'Save'). A higher number of bits for 'Red', 'Green' or 'Blue' will increase
the accuracy with which the corresponding colour component is handled. Note
however that selecting more than the default of 5 bits per colour component
results in only very marginal and mostly unnoticable differences in image
quality. Also note that selecting less than 5 bits is not really recommended
except for the possible entertainment value that the resulting images provide.
Also note that the memory requirements for the quantization tables double with
every bit added to the total number of bits. The default setting of 5 bits per
colour component (15 bits total) requires around 128 KB of processing memory.

The 'Dithering' part allows you to select the accuracy of the colour mapping
tables used during colour dithering. Comments similar to the comments under
'Quantization' apply. 15 bits, again, translate to 128 KB.


//
//
// The 'Choices' menu
//
//

In this menu you can manipulate Translator's 'choices'.

- 'Save' will save the current choices.
- 'Load' will load the saved choices.
- 'Default' will load the default choices.
- 'Kill' will discard the saved choices.

When Translator starts up it loads the saved choices, or the default choices if
no choices were saved.

The choices consist of all the settings in the 'Options' window.


//
//
// Batch processing
//
//

If you have a large number of images that you want processed in exactly the
same way, Translator can do this for you automatically, saving you a lot of
time. Translator performs 'batch processing', as this functionality is commonly
called, 'by example'. This means you have complete freedom of doing whatever
processing you need to be done, in any order you want.

All image files to be processed must be put in the same directory. You simply
load one of the images (any of them will do), perform your processing on it,
and click on the 'Do others' icon on Translator's iconbar menu. All the other
images in the directory are now loaded and processed in exactly the same way.

There are a few things to note :

- Translator 'replays' the processing done on the *last loaded image*. I.e.
  every time you load a new image, Translator forgets about the processing done
  on the previously loaded image.
- Selections are not remembered. If you used selections while processing your
  example image, during batch processing the whole image will be affected
  instead. You will be warned if you have used selections.
- The 'crop' operation is not remembered. If you used 'crop' while processing
  your example image, during batch processing it is not executed. You will be
  warned if you have used 'crop'.
- 'Closing' an image, i.e. deleting it, is a perfectly valid processing step
  (and for obvious reasons always the last one too). In fact, if you do not
  close your example image, you will end up with all your 'replayed images'
  still loaded.
- When you perform a save, you may save to a different directory than the
  directory from which the image was loaded (though you don't need to), but you
  must *not* change the leafname of the target file. Translator remembers the
  target directories used during the 'example saves'. The 'replayed saves' will
  automatically save to the same target directories as the 'example saves' but
  will use the leafname of the original image.
- If you have a set of images of varying sizes and you need to scale all of
  them to a fixed number of pixels, remember to use the special 'x' and 'y'
  divisors when scaling (refer to the discussion of 'Transform -> Scale' for
  more details).
- Batch processing continues after any errors. However, you may pause batch
  processing at any time by holding down a CTRL key. If you need to abort
  completely, e.g. if your house is on fire, or martians have just landed in
  your yard, then while holding down CTRL, you can quit Translator in the usual
  way (and by this I mean the 'Quit' icon).
- There is no need to do any specific processing. In particular you do not need
  to save. E.g. if you simply load the example image, close it again, and click
  'Do others', you have made yourself a simple slideshow (and you can use CTRL
  to pause).


//
//
// The Clear file format
//
//

Some considerable number of years ago, I designed the Clear graphics file
format to circumvent some old Sprite format restrictions (largely corrected
these days), and to have an easy to understand 'lowest common denominator'
graphics file format, to ease pre- and post-processing of images (outside
Translator).

Clear files contain 1, 2, 3, 4, 5, 6, 7 or 8 bits per pixel paletted, or 24
bits per pixel true colour images.

The exact format is as follows (the descriptions are somewhat verbose to avoid
misinterpretation, the format is actually extremely simple) :

Offset  Bytes   Description
-------------------------------------------------------------------------------
0       m       Informational string (can be ignored usually)
m       1       0 (string terminator)
m+1     4       Informational value (can be ignored usually)
m+5     4       Width of image in pixels (w)
m+9     4       Height of image in pixels (h)
m+13    4       Bits per pixel (bpp)
m+17    n       Palette entries
m+17+n  w*h*l   Pixel values
----------------------------------------------------------------------------

Palette entries are byte triples representing a 24-bit RGB colour : first red
(0-255 = no-full intensity), then green, then blue. The first entry represents
colour 0, the second colour 1, and so on.

Pixel values represent the image in rows from top to bottom, and within every
row from left to right (the first pixel is the top left one, the last is the
bottom right one).

If 1 <= bpp <= 8, n = 3 * 2 ^ bpp (i.e. 2 ^ bpp palette entries appear) and l =
1 (every pixel value takes up one byte (c), and palette entry c represents the
pixel's colour).

If bpp > 8, n = 0 (there's no palette) and l = 3 (every pixel value takes up
three bytes, and is like a palette entry (red first, then green, then blue),
indicating the pixel's colour).

Note that when 1 <= bpp <= 8, only pixel values 0 through 2 ^ bpp - 1 will
appear in the file.


//
//
// Supported image formats (overview)
//
//

Translator can read the following image formats (in alphabetical order) :

- AIM
- BMP
- CadSoft
- Clear
- Degas
- Draw
- GIF
- IFF
- ImageIO
- IMG
- Irlam
- JPEG
- MacPaint
- MTV
- PBMPlus
- PCX
- Pineapple
- PNG
- QRT
- Sprite
- TIFF

Translator can write the following image formats (in alphabetical order) :

- BMP
- Clear
- GIF
- ImageIO
- JPEG
- PBMPlus
- PNG
- Sprite
- TIFF

The 'ImageIO' format is a special 'internal' format which is not meant to be
used outside Translator.

For more details about the image formats that Translator supports, see
'Supported image formats (detailed)'.

For some image formats that Translator understands, you may specify a few
special settings to be used when loading or saving an image in that format.
Refer to the discussion of the 'Load options' and 'Save options' parts of the
'Options' window.


//
//
// Supported image formats (detailed)
//
//

Following are brief details of all supported image formats.

Image format interpreters are usually complete, but may, in some cases, lack
support for some particular subformats. All image format interpreters have at
least been tested successfully on all sample images I could find, and have been
verified as well as possible against documentation available to me. Generally,
if Translator encounters formats or subformats that cannot be recognized or are
not supported, it will give up gracefully and provide an indication of why it
has failed.

AIM
===
- Origin
  Acorn machines. !AIM (Archimedes Image Manager) program.
- Colours
  8 bpp 8:8:8 grey
- Compression
  none
- Recognition
  filetype &004
- Miscellaneous
  Resolution is always 256 x 256 pixels.

BMP
===
- Origin
  IBM compatible machines. Microsoft Windows operating system.
- Colours
  1 bpp 8:8:8 palette
  4 bpp 8:8:8 palette
  8 bpp 8:8:8 palette
  24 bpp 8:8:8 true
- Compression
  none
  runlength
- Recognition
  filetype &69C
  'BM' at offset &0

CadSoft
=======
- Origin
  Acorn machines. Millipede Prisma display board.
- Colours
  8 bpp 8:8:8 palette
- Compression
  none
  runlength
- Recognition
  filetype &69A
  'MILLIPEDE' at offset &10

Clear
=====
- Origin
  Acorn machines. !Translator program and several hardware vendors' programs.
- Colours
  1,2,3,4,5,6,7,8 bpp 8:8:8 palette
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &690

Degas
=====
- Origin
  Atari machines. Degas and other programs.
- Colours
  1,2,4 bpp 3:3:3 palette
- Compression
  none
  runlength
- Recognition
  filetype &691

Draw
======
- Origin
  Acorn machines. Acorn defined native vector image format.
- Colours
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &AFF
- Load options
  'X*', 'X/', 'Y*' and 'Y/' specify scaling. Scaling is by 'X*' divided by 'X/'
  horizontally, and by 'Y*' divided by 'Y/' vertically.
- Miscellaneous
  Only available on machines running RISC OS 3.60 or higher.

GIF
===
- Origin
  Various machines. Graphics Interchange Format, devised by and copyright of
  Compuserve Incorporated.
- Colours
  1,2,3,4,5,6,7,8 bpp 8:8:8 palette
- Compression
  12-bit LZW
- Recognition
  filetype &695
  'GIF87a' or 'GIF89a' at offset &0
- Miscellaneous
  When reading, any GIF89a extensions are skipped and ignored. When writing,
  GIF87a format is always used.
- Save options
  'Interlace' defines whether or not an interlaced image is saved. 'Interlace
  = Yes' will save an interlaced image, 'Interlace = No' won't.

IFF
===
- Origin
  Various machines. Interchange Format File, devised by Electronic Arts.
- Colours
  1,2,3,4,5,6,7,8 bpp 4:4:4 palette
  1,2,3,4,5,6,7,8 bpp 8:8:8 palette
  12 bpp 4:4:4 true
  24 bpp 8:8:8 true
- Compression
  none
  runlength
- Recognition
  filetype &693
  'FORM' at offset &0 and 'ILBM' at offset &8

IMG
===
- Origin
  Atari and IBM compatible machines. Digital Research GEM programs.
- Colours
  1 bpp 8:8:8 grey
- Compression
  various methods
- Recognition
  filetype &692

Irlam
=====
- Origin
  Acorn machines. Irlam video digitiser.
- Colours
  24 bpp 8:8:8 grey
- Compression
  none
- Recognition
  filetype &69B
  'Irlam' at offset &0

JPEG
====
- Origin
  Various machines. Joint Photographic Expert Group, the actual format is
  called JFIF (JPEG File Interchange Format), devised by C-Cube Microsystems.
- Colours
  8 bpp 8:8:8 grey
  24 bpp 8:8:8 true
- Compression
  Baseline JPEG
- Recognition
  filetype &C85
  &FF, &D8 at offset &0
- Load options
  'Float DCT = No' uses 'fast' integer DCT (Discrete Cosine Transform) code.
  'Float DCT = Yes' uses slightly more accurate but 'slow' floating point DCT
  code. In practice, both option settings nearly always result in the same
  image quality.
- Save options
  'Quality = xx', where xx = 0..100, sets the quality level. 100 is best
  quality, lowest compression. 0 is worst quality, highest compression.
  'Optimize' switches on/off compression optimization (switching it on
  results in somewhat smaller files but also uses more processing time).
  'Optimize = Yes' switches on compression optimization. 'Optimize = No'
  switches it off.
- Miscellaneous
  - Processing code is in C. Acknowledgements :
    - Compiled with GCC for RISC OS 2.95.4, (c) 1996-2001 Nick Burrett.
    - Uses IJG JPEG library 6b (27 Mar 1998), (c) 1991-1998 Thomas G. Lane
      I am required to state that 'This work is based in part on the work of
      the Independent JPEG Group'.

MacPaint
========
- Origin
  Apple MacIntosh machines. MacPaint program.
- Colours
  1 bpp 8:8:8 grey
- Compression
  runlength
- Recognition
  filetype &694
  'PNTG' at offset &41
- Miscellaneous
  Resolution is always 576 x 720 pixels.

MTV
===
- Origin
  Various machines. MTV ray tracer.
- Colours
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &699

PBMPlus
=======
- Origin
  Unix machines. Portable Bit Map set of conversion programs, devised by Jef
  Poskanzer.
- Colours
  1,2,3,4,5,6,7,8 bpp 8:8:8 grey
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &69E
  'Px' at offset &0, where x = 1,2,3,4,5,6
- Miscellaneous
  Cannot save 2..7 bpp 8:8:8 grey.

PCX
===
- Origin
  IBM compatible machines. ZSoft PC Paintbrush program.
- Colours
  1,2,4,8 bpp 8:8:8 palette
- Compression
  none
  runlength
- Recognition
  filetype &697

Pineapple
=========
- Origin
  Acorn machines. Pineapple Software video digitiser.
- Colours
  16 bpp 5:6:5 true
- Compression
  none
- Recognition
  filetype &696
  'FSIfile' at offset &0
- Miscellaneous
  Resolution is always 512 x 256 pixels.

PNG
===
- Origin
  Various machines. Portable Network Graphics format, initially designed to
  impove on and fully replace GIF, since GIF's compression algorithm poses
  patent problems since 1995. Forget GIF, use PNG (compresses better too !).
- Colours
  1,2,4,8 bpp 8:8:8 palette
  1,2,4 bpp 8:8:8 grey
  8 bpp 8:8:8 grey with optional alpha channel
  16 bpp 16:16:16 grey with optional alpha channel
  24 bpp 8:8:8 true with optional alpha channel
  48 bpp 16:16:16 true with optional alpha channel
- Compression
  Deflate
- Recognition
  filetype &B60
  137, 80, 78, 71, 13, 10, 26, 10 at offset &0
- Save options
  'Interlace' defines whether or not an interlaced image is saved. 'Interlace
  = Yes' will save an interlaced image, 'Interlace = No' won't.
- Miscellaneous
  Reader supports all formats, but :
  - 16 bpp 16:16:16 grey is 'stripped' to 8 bpp 8:8:8 grey.
  - 48 bpp 16:16:16 true colour is 'stripped' to 24 bpp 8:8:8 true colour.
  - Alpha channels and transparency cause pixel colours to be recalculated
    against a background colour (black if not specified in PNG file).
  - Processing code is in C. Acknowledgements :
    - Compiled with GCC for RISC OS 2.95.4, (c) 1996-2001 Nick Burrett.
    - Uses libpng 1.2.1, (c) 1998-2001 Glenn Randers-Pehrson.
    - Uses zlib 1.1.3, (c) 1995-1998 Jean-loup Gailly and Mark Adler.

QRT
===
- Origin
  Various machines. QRT ray tracer.
- Colours
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &698

Sprite
======
- Origin
  Acorn machines. Acorn defined native pixel image format.
- Colours
  1,2,4,8 bpp 4:4:4 palette
  1,2,4,8 bpp 8:8:8 palette
  15 bpp 5:5:5 true
  24 bpp 8:8:8 true
- Compression
  none
- Recognition
  filetype &FF9
- Load options
  'Default palette' defines the palette to use when palette colour sprites
  without a palette are loaded. If the mapping of the bpp of the input to the
  corresponding mode is thought of as 1,2,4,8 bpp --> mode 18,19,20,21, then
  'Default palette = WIMP' will use the default WIMP palette for the
  appropriate mode, and 'Default palette = Mode' will use the default mode
  palette (as after a MODE command outside the desktop).
- Save options
  'Sprite type' defines the sprite type to save. It only affects the mode
  number saved in the sprite file. 'Sprite type = Default' will save old type
  sprites for 4:4:4 palette colour input, else new type sprites. 'Sprite type
  = Force old' will always save old type sprites. 'Sprite type  = Force new'
  will always save new type sprites.
- Miscellaneous
  Sprite masks are always ignored. Old type 8 bpp 4:4:4 sprites always have
  the standard fixed 256-colour palette and are actually saved without
  palette.

TIFF
====
- Origin
  Various machines. Tag Image File Format (that's 'Tag', not 'Tagged' as most
  people think !), devised by Aldus Corporation and Microsoft Corporation.
- Colours
  1,2,4,8 bpp 8:8:8 palette
  1,4,8 bpp 8:8:8 grey
  24 bpp 8:8:8 true
- Compression
  none
  PackBits
  12-bit LZW
  Modified Huffman
  Group 3 Fax
- Recognition
  filetype &FF0
  'II' or 'MM' at offset &0
- Save options
  'Endian' selects between saving in 'big endian' or 'little endian' format.
  The official TIFF docs recommend using 'big endian', although TIFF readers
  are required to handle both types. 'Prediction' selects whether or not
  'prediction' is used. If used, it is only in effect when the 'Compression'
  setting in the 'Save image' window is '12-bit LZW' and the 'Colours'
  setting is either '24 bit 8:8:8 true' or '8 bit 8:8:8 fixed grey'. Using
  'prediction' in these cases almost always results in a smaller output file.


//
//
// Registering Translator
//
//

This version of Translator is 'key locked'. It 'nags' when you load or save an
image or use a processing function. When you register Translator, a key will be
emailed to you, which, when installed, will stop Translator nagging. Note that
keys will be sent by email only. If you're already registered, please email me
to obtain a key, quoting the name and address you used when you registered, how
much you paid, and approximately when.

You can register your copy of Translator by paying 15 Euro. If possible, email
me first for (possibly changed) details.

You can pay in one of the following ways, in order of preference :

- Online with PayPal

  Please pay 17 Euro total to cover PayPal costs.

  Go to (on Internet) :

  http://web.inter.nl.net/users/J.Kortink/home/software/translator/index.htm

  and follow the instructions.

  Alternatively, simply go to www.paypal.com, follow 'Send money', and pay to
  kortink@inter.nl.net.

- Sending bank notes

  Take a piece of paper, fold it, slip 15 Euro or 10 UKP (in banknotes only,
  please) in between, scribble your snail mail and email address on the paper,
  slip it in an envelope, stamp it, email me to obtain the address to send it
  to, and mail it.

Please note that I cannot accept ways of payment other than cash and PayPal.

As soon as your money arrives you are a registered user of Translator. This
entitles you to free and continued use of all current and future Shareware
versions of Translator.

Note that Translator is part of a two application package : Translator and
Creator (GreyEdit, which used to be a part of the package as well, is now
freeware). This means that when you register Translator, you are automatically
registered for Creator as well, for free.


//
//
// Epilogue
//
//

Updates of Translator (if any appear) will be made available by (in order of
preference) :

- World Wide Web : visit web.inter.nl.net/users/J.Kortink
- Electronic mail : email kortink@inter.nl.net

Enjoy !


John Kortink



