home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 2 / AUCD2.iso / resource / changfsi.spk / !ChangeFSI / FSIinfo < prev    next >
Text File  |  1996-03-11  |  54KB  |  1,022 lines
  1.      ChangeFSI: Colour Image Processing Using the 256 colour modes
  2.  
  3. Archimedes computers have full colour display capabilities built into them as
  4. standard. However, compared with the hardware found in larger workstations, the
  5. facilities provided have been carefully reduced (in order to make them cheap
  6. enough to fit all the time). So the precision of the digital to analogue
  7. converters is only 4 bits (instead of 8) and the colour palette only has 16
  8. entries (instead of 256).
  9.  
  10. The VIDC 256 colour mode
  11. =========================
  12.  
  13. Has 4 direct bits (top 2 green, top red and blue) plus 4 palette look up bits
  14. which affect the remaining DAC bits. This therefore gives a choice of 256
  15. colours from 4096, but the choice is not a free one in that the 4 direct bits
  16. are always connected: this leaves only 256 selections available from the 4096
  17. colour range. To repeat: there are 256 simultaneous colours in a selection out
  18. of 4096 colours, where there are only 256 "legal" selections. The new VIDC20
  19. allows an arbitrary selection of colours, but the default situation is
  20. identical.
  21.  
  22. There are "optimal" selections. An optimal selection is one which covers the
  23. entire R, G, B colour cube (i.e. 0-fullscale for each of the colours) and can
  24. thus be dithered to from any picture (if one considers picture's colour range
  25. as an arbitrary volume in the colour cube, then you can dither/display a
  26. picture accurately if and only if the volume covered by the available colours
  27. encloses the picture's). The optimal selection used for the RISC OS 256 colour
  28. mode palette contains 2 most significant bits of Red, 2 most significant bits
  29. of Green and 2 most significant bits of Blue, with the last 2 bits controlling
  30. the 2 least significant bits in parallel ("adds white" to a colour). Thus peak
  31. R, G, B is obtained (without side effects if varied simultaneously, with a side
  32. effect if peak R (say) alone is required). A correctly designed error diffusion
  33. dither algorithm can display pictures with very high fidelity. [note that
  34. dithering all pictures with a single palette permits their display
  35. simultaneously on the screen, also note that dithering to a fixed palette is
  36. much quicker than selecting a palette first!]
  37.  
  38. One can also program the system for a large number of n bits per colour modes,
  39. with the n bits starting at the most significant end of the colour range. For
  40. example 4 bits of green, 3 bits of red and 1 bit of blue. The constraints are:
  41.      2 <= nGreen <= 4
  42.      1 <= nRed   <= 4
  43.      1 <= nBlue  <= 4
  44.      (and nRed+nBlue+nGreen=8)
  45. Modes like these are often useful for real time solid modelling (where the
  46. expense of dithering with error diffusion (circa 100 cycles per pixel) cannot
  47. be afforded). These selections are non-optimal: the colour cube is not
  48. completely spanned.
  49.  
  50. Displaying A Picture
  51. ====================
  52.  
  53. Since a colour in the 256 colour mode can be such a complicated thing, with
  54. varying capability of spanning the colour cube and an unknown accuracy, there
  55. is a RISC OS standard way of specifying a colour you wish to draw with using 8
  56. bits for R, G and B components. A call to the operating system converts this to
  57. the nearest colour and new objects can be drawn.
  58.  
  59. Where the object to be drawn is a previously generated picture, the modules
  60. "SpriteExtend" (in the ROM) and "ColourTrans" (in the !System directory) in
  61. RISC OS provide some capabilites for displaying pictures in different screen
  62. modes. ColourTrans can look at the palette which a sprite uses and return a
  63. list of the equivalent 'closest' colours in the current screen mode.
  64. SpriteExtend can paint sprites using the list of equivalent colours and can
  65. change the size of the image into the bargain. This is all very well for simple
  66. pictures or pictures created directly for a particular mode, but what happens
  67. for more detailed information or pictures from other sources with resolution
  68. not matched by the Archimedes hardware?
  69.  
  70. Also the above facilities are rather basic: ColourTrans makes no effort to use
  71. dithering (the practise of putting patterns of different coloured pixels
  72. together to represent other colours) and SpriteExtend simply discards
  73. additional information if reducing the picture in size (and together they make
  74. no attempt to enhance the picture when making it larger). The reason for these
  75. shortcomings is quite simple: speed. The algorithm used in ChangeFSI uses 105
  76. ARM instructions per pixel - and that's apart from any instructions used to
  77. read the image in, change its size and write the result out. For comparison,
  78. the normal sprite plot takes only one instruction per pixel (4 instructions for
  79. four 8 bit pixels). Processing a MODE 15 picture thus uses up too many seconds
  80. of ARM cpu time to imagine it as part of the interactive desktop.
  81.  
  82. So what does ChangeFSI do to make the situation better? And why does it take so
  83. long? One can immediately draw up some desirable properties for any solution to
  84. the image changing problem:
  85.  
  86. (1) Maximising the volume of the colour cube. Colour represented in the Red,
  87. Green and Blue computer graphics system can be thought of as a point in a 3D
  88. cube whose axes are the red, green and blue values. Whatever clever
  89. approximations, dithering or error diffusion techniques are used, the colour
  90. volume spanned by the r, g and b axes in the target should be large enough to
  91. contain the source volume. If not, then the picture will appear faded in some
  92. way compared to the original ("the red doesn't seem quite the same"). For a
  93. single picture a colour volume only as large as the input could be chosen;
  94. alternatively for an arbitrary set of input pictures, the colour volume on the
  95. output system has to be made as large as possible. Where animation is required
  96. the colour volume has to be consistent for all the pictures. When generating
  97. the largest volume, it is important to use the system hardware to the limit:
  98. for example, if one has two bits of control over the Archimedes 4 bit D to A
  99. converters, the largest range is covered by values 0, 5, 10 and 15 (rather than
  100. 0, 4, 8 and 12).
  101.  
  102. (2) Giving hue consistency at different saturations. For example, with a
  103. palette with different numbers of bits of r, g and b it may be impossible to
  104. have a consistent set of colours representing derived colours at different
  105. levels of intensity. Shades of white and secondary colours (cyan, magenta and
  106. yellow) are particularly difficult.
  107.  
  108. (3) Working with the multi-tasking desktop. Acorn are asking for all new
  109. software to be built on the multitasking system. This implies that the palette
  110. should not be changed (or that the agreement of all programs currently running
  111. is obtained first).
  112.  
  113. The desktop (default) palette in the 256 colour modes (e.g. modes 13, 15, 21,
  114. 24 and 28) is quite well designed. It does have the properties of (1) and (2)
  115. (it even has 16 shades of grey) and automatically satisfies (3). It is used by
  116. many Acorn programs (Draw, Paint) and by external programs (Euclid, ProArtisan,
  117. Atelier, ..) to great effect and is a safe choice for ChangeFSI. There are two
  118. ways ChangeFSI can choose a colour:
  119.  
  120. (a) a method which derives values for r, g, b and tint algorithmically (no
  121. suffix) (suitable only for the default RISC OS 256 colour palette)
  122.  
  123. (b) search the palette for the closest colour (r suffix). The precise method by
  124. which this is done is the subject of another document.
  125.  
  126. ASIDE: the closest colour is chosen such that the distance between the true
  127. colour and the choice is minimised in the colour cube space. Since the human
  128. eye is more sensitive to green, then red and lastly blue, the distance function
  129. is weighted 10, 3 and 1 in green's favour.
  130.  
  131. With the 16 colour modes (e.g. modes 9, 12, 16, 20 and 27) the default palette
  132. does not satisfy (1) and (2) unless the output is purely shades of grey -
  133. ChangeFSI can use either 8 greys (for the desktop) or 16 greys (out of the
  134. desktop or with the desktop palette altered to provide 16 greys). For colour
  135. representation, ChangeFSI can either:
  136.  
  137. (a) use 1 bit of red, 1 bit of green and 1 bit of blue (i.e. the standard 8
  138. digital colours Black, Red, Green, Blue, Yellow, Magenta, Cyan and White). This
  139. spans the colour cube and is hue consistent, but doesn't use the full range of
  140. bits provided in the format. ColourTrans can map this to the desktop with the
  141. standard palette with fair success, except for the lack of magenta (full
  142. red+full blue) in the palette. A better result can be achieved by setting 6 of
  143. the colours in the palette to red, green, yellow, blue, magenta and cyan. Since
  144. ColourTrans will map the colours anyway, it doesn't matter which 6, but the
  145. most consistent values are 8=blue, 9=yellow, 10=green, 11=red, 13=cyan,
  146. 14=magenta (leaving 0-7, 12 and 15 unchanged). This option is selected by a "d"
  147. (digital RGB) suffix to the program's mode argument.
  148.  
  149. or (b) search the palette for the closest colour (r suffix) [ChangeFSI needs to
  150. be in the 16 colour mode in order to read the palette]
  151.  
  152. With the 4 colour modes (e.g. modes 8, 11, 19 and 26) ChangeFSI is really
  153. pushed. Shades of grey output is done with the 0, 5, 10, 15 level palette. But
  154. how can colour be done? For example, each pixel can display only one of (say)
  155. black, red, green or blue. This fails to span the colour cube (it does only
  156. half of it), however, so black, cyan, magenta and yellow are used instead. The
  157. rest has to be left to luck: there is no way it can approximate to pure shades
  158. of red, green or blue. 4 bit colour pictures can be seen on the desktop in 16
  159. colour modes with the above palette or in 256 colour modes. This option is by a
  160. "c" suffix. If you can provide a better palette, then ChangeFSI can use it with
  161. the "r" suffix search method.
  162.  
  163. With 2 colour modes (e.g. modes 0, 18, 23 and 25) pixels are either ON or OFF,
  164. ChangeFSI will only do shades of grey output.... However, the method used can
  165. be varied (see later).
  166.  
  167. So that's the canvas ChangeFSI has to work on. How does it display the input
  168. range of colours on these outputs? The answer is, as stated above, dithering:
  169. the process of approximating intensity variations with patterned areas. There
  170. are two basic types of dithering technique: that used to print colour magazines
  171. and newspaper photographs "clustered dot dither" - the size of the dot of ink
  172. gives the intensity; and that used on dot matrix displays, for example the grey
  173. level patterns used by 1 bit per pixel mode on the desktop "dispersed dot
  174. dither" where the average number of dots in the area gives the intensity.
  175.  
  176. Why does the world need two different techniques? Well, different devices
  177. reproduce pixels differently. The "ideal square" pixels produced by an LCD are
  178. perfect for dispersed dot dither; a CRT produces a gaussian spot (a circle or
  179. ellipse which decays in intensity towards the edges) instead of a square -
  180. dispersed dot dither works well; a dot matrix impact printer or a "write black"
  181. laser printer produce large dots (diameter at least SQR(2) over unit pixel
  182. square) and thus make pictures too dark if dispersed dot dither is used; a
  183. "write white" laser printer prints negative "white dots" on a black field and
  184. thus "caves in" the sides of pixels making pictures too white with dispersed
  185. dot dither. Clustered dot dither reduces the effects of mis-sized pixels by
  186. ensuring they are adjacent (and thus the error is confined to the periphery of
  187. the shape) but this does have a cost in poorer resolution.
  188.  
  189. Since ChangeFSI's colour or greyscale output is to CRTs (or LCDs in some
  190. distant future) it automatically uses a dispersed dot dither. Monochrome output
  191. could be for the screen or for a printer: the user can select between dispersed
  192. and clustered methods by adding a various suffices ("c", "d" or "t") to the
  193. mode number for clustered output. For "c" the algorithm (due to Robert L Gard,
  194. 1976) approximates tones in the range 0..16 (17 levels) by using 0..16 "on"
  195. pixels in a 4 by 4 cell. For "d" the algorithm (developed by me, but similar to
  196. Gard's) approximates tones in the range 0..4 (5 levels) by using 0..4 "on"
  197. pixels in a 2 by 2 cell. For "t" the algorithm (ditto as "d") approximates
  198. tones in the range 0..9 (10 levels) by using 0..9 "on" pixels in a 3 by 3 cell.
  199. The "on" pixels are carefully chosen to provide: (a) symmetry of white/black
  200. and black/white patterns (b) diagonally oriented dot grid. The diagonal angle
  201. reduces the eye's ability to see the rectangular patterns produced. The various
  202. sizes of the halftone cell allow some trade off between representing the tonal
  203. values correctly and loss of resolution. Start with "c" and progress to "t" and
  204. then "d" if the resolution is not acceptable.
  205.  
  206. ChangeFSI can generate reasonable pictures on "write black" printers with a
  207. dispersed dot dither by using the "-black" parameter; however images produced
  208. like this do not photocopy at all well (the photocopier makes the dots blacker
  209. again!). The parameter to -black (default value 32, range 0..128) tells
  210. ChangeFSI how much larger than the ideal square pixel the dots produced by the
  211. printer are - 128 corresponds to an inked dot covering four times the area of
  212. the ideal black square pixel (and this will generally mean ChangeFSI produces
  213. an entirely white output!). Values above 64 give rather poor results on some
  214. pictures but may be worth experimenting with. The default is 32, a dot covering
  215. 50% more area than the square pixel (the minimum circle enclosing the pixel
  216. square). Some printers produce dots of (pseudo-randomly) varying sizes and
  217. black correction may not help with these (the picture looks "noisy") in which
  218. case use one of the clustered output methods. -black correction makes pictures
  219. on the screen look very pale, since, if anything, black pixels on screen are
  220. smaller than the ideal square.
  221.  
  222. [aside: to print these pictures, you need a method which copies the pixels
  223. ChangeFSI has made exactly to those of the output device. Using !Paint, scale X
  224. and Y by 90:300 for a 300dpi printer.]
  225.  
  226. In all cases, an approximation to a colour will produce an error (which might
  227. possibly be zero if ChangeFSI is very lucky). ChangeFSI tracks these errors and
  228. ensures that over wide areas there is no overall error using a technique called
  229. "error diffusion", first devised by R W Floyd and L Steinberg in 1975. In this
  230. technique the approximation is made and the error distributed to nearby pixels
  231. in the following ratios:
  232.  
  233.                 current pixel   7/16 of error
  234. 3/16 of error   5/16 of error   1/16 of error
  235.  
  236. ChangeFSI gets some of its name from Floyd and Steinberg. Additionally,
  237. ChangeFSI scans through the picture in a serpentine fashion, doing a row of
  238. pixels left to right followed by the next row right to left. This reduces the
  239. probability of regular patterns which the eye is sensitive to. The final I of
  240. the name is for Integer: ChangeFSI does all its work in 32 bit fixed point
  241. integer arithmetic (with the point at bit 28) instead of floating point.
  242. Dithering can be turned off using using "Disable Dithering" on the Processing
  243. dialogue ("-nodither" on the command line) which at least allows you to see how
  244. well it does!
  245.  
  246. The conversion from one colour range to another is made at the same time as a
  247. change in size of the image. Size is changed by ratios of areas between the
  248. input and output: the total weight of r, g, and b in the source area is
  249. calculated using the fixed point arithmetic and this result is then
  250. approximated to the output using the error diffusion to preserve information
  251. (for example, consider halving in size an image with adjacent pixels of
  252. intensities 1 and 2; the output pixel needs to be value 1.5, so the 0.5 error
  253. is sent to adjacent pixels to keep the overall colour the same). The size
  254. change is expressed as a ratio of output to input (e.g. 40:20) which ChangeFSI
  255. reduces to the smallest possible terms (2:1 in this case) so that you are free
  256. to give values like 256:512 if that's what you mean! Size change is either both
  257. x and y (if one ratio is given) or separate x and y (if two ratios are given).
  258. Note that the size of a RISC OS pixel is known, so changing from (say) mode 21
  259. to (say) mode 13 does not need any additional specified scaling. The full size
  260. output for mode 21 is the reference, so scale to 640 by 512. A common scaling
  261. is to fill the output sprite with the input and an "=" parameter to x and/or y
  262. ratios will do this without ever having to know the size of the input. Simply
  263. omitting the fractional part causes ChangeFSI to put in the source size, thus
  264. giving output which is the specified number of pixels in size.
  265.  
  266. Conversion from colour to monochrome shades of grey is done with the CIE
  267. luminance weights for r, g and b (0.299, 0.587, 0.114) which is the standard
  268. conversion for broadcast television. These values can be altered using the
  269. -red, -green and -blue commands and allow different weightings for conversion
  270. to monochrome to be tried, this also allows selection of an image composed of
  271. only some of the colours (e.g. -red1 -green0 -blue0) in making a black and
  272. white image.
  273.  
  274. ChangeFSI can take any RISC OS sprites (2, 4, 16 or 256 colours). If there is a
  275. palette it will be used, otherwise the standard 2, 4, 16 and 256 colour desktop
  276. palettes are used. ChangeFSI can also read the 16bpp and 24bpp sprites which
  277. have no palettes.
  278.  
  279. ChangeFSI is both a command line driven program and a desktop application. The
  280. file !Help describes how to use the application from the desktop, if you need
  281. to use the program as a command line driven program you will need to have it in
  282. the library (or on run$path) and press f12 to get out of the desktop. The file
  283. "FSIuse" describes the parameters concisely. The program selects mode 0 when
  284. run from the command line when doing any work in order to speed up processing
  285. (this can be disabled with -nomode). It may also be a good idea to RMFaster
  286. BASIC. An hourglass %age processed figure is displayed (this may run through
  287. twice for some of the more expensive options). The program reads the source
  288. image from disc and builds the output in memory, having claimed some from the
  289. system.
  290.  
  291. In addition to strictly converting the source image, ChangeFSI can also process
  292. it. A trivial option is "-info": ChangeFSI will tell you what it is doing (a
  293. good way of finding out what the source image actually is, and how the scaling
  294. turns out!). Similarly trivial are -vflip and -hflip - the picture can be
  295. produce upside down and left/right reversed. Not so trivial is -rotate, which
  296. will rotate the image by 90 degrees (that is, an anti- clockwise quarter turn).
  297. -rotate- rotates by -90 degrees (clockwise quarter turn).
  298.  
  299. Sometimes useful is "-nosize": ChangeFSI can read pixel size information from
  300. the source image (if present) or guess it (e.g. if there are less than 320 by
  301. 256 pixels in a source image, ChangeFSI assumes the pixels are the same size as
  302. MODE 13's [45 per inch]) or derive it from other information and scale the
  303. output image (composed of RISC OS square or 1:2 sized pixels) appropriately.
  304. -nosize stops this from happening. [this seems particularly relevant on formats
  305. like TIFF or IFF where the pixel size is specified *but may be wrong*] Using
  306. -info will display the pixel ratios which ChangeFSI is using - a combination of
  307. the size guess, the output pixel size and any deliberate scaling. "-noscale"
  308. turns off the output scaling as well.
  309.  
  310. The simplest image processing option is "-range" which will expand the dynamic
  311. range of the input picture so that it fills the available area (not a good
  312. option for animated sequences unless all source images possess the same range).
  313. Since r, g, b are processed by the same amount, -range preserves the colour of
  314. pixels in coloured pictures.
  315.  
  316. A useful option for output intended for the screen only is Gamma correction.
  317. CRT displays do not have a simple linear relationship between brightness of the
  318. spot and input voltage: instead of brightness = const * voltage, the response
  319. is brightness = const * voltage ^ (1/gamma). In the TV industry, gamma has been
  320. standardised as 2.2, but there is wide variation in the computer industry: the
  321. monitor's response will vary depending on what make it is and how it is
  322. adjusted. Low values of gamma (0 to 1) make colours darker and high values
  323. (above 1) make colours lighter with the effects being particularly noticeable
  324. on dim colours. "-gamma" uses the default of 2.2, and it can be set by
  325. "-gamma1.5" say. Gamma correction is most relevant when its known that the
  326. input has a linear intensity (input from a scanner or from another computer
  327. with more bits per colour component than the Archimedes).
  328.  
  329. A more complex primitive is "-equal" which performs "histogram equalisation" on
  330. the image. This makes the histogram of level versus number of points at that
  331. level as flat as possible giving full use of the number of colours available.
  332. -equal is a very harsh primitive, even on monochrome inputs it can produce an
  333. inferior picture; while on colour pictures it can distort the colour of each
  334. point (since r, g, b are computed separately). But -equal can often recover a
  335. picture that is otherwise completely useless or expose information locked in a
  336. small part of the input scale.
  337.  
  338. Image colours may be inverted with the -invert option. Which may be fun in
  339. colour but is rarely useful! However, monochrome images frequently need
  340. inverting, especially one bit per pixel sources.
  341.  
  342. A more powerful option is "-sharpen" which enhances the edges of objects in the
  343. picture: this is very useful since the dithering process inevitably smears
  344. information over the display. Pre-sharpening the image can result in a more
  345. acceptable output. Default values of sharpening can be overridden for special
  346. effects: -sharpen8 does edge detection. Lower amounts of sharpening are
  347. obtained with larger -sharpen numbers. In general the more input and output
  348. pixels and the greater the output range in a pixel in the images, the less
  349. sharpening is required. Sharpening a picture which is already dithered can give
  350. a very bad result....
  351.  
  352. The sharpening is achieved with the following matrix:
  353.  
  354.    -1    -1    -1
  355.    -1 sharpen  -1
  356.    -1    -1    -1
  357.  
  358. ChangeFSI computes the sum of nine pixels with the above weights for each input
  359. pixel and renormalises the result (divides by sharpen-8).
  360.  
  361. Similar is "-smooth" which averages the pixels to eliminate noise. It uses the
  362. following matrix:
  363.  
  364.     1     1     1
  365.     1  smooth   1
  366.     1     1     1
  367.  
  368. ChangeFSI computes the sum of nine pixels with the above weights for each input
  369. pixel and renormalises the result (divides by smooth+8). Only one of smoothing
  370. or sharpening may be performed (whichever is last on the command line).
  371.  
  372. An option for testing is "-nodither" which disables the Floyd Steinberg error
  373. diffusion step completely. Versions after 6th June 1990 are more accurate at
  374. doing this.
  375.  
  376. The various processes described above are applied in the following order for
  377. pictures with more output pixels than input:
  378.    (a) range or histogram equalisation,
  379.    (b) sharpen or smooth,
  380.    (c) scale,
  381.    (d) error diffusion.
  382. This order is chosen so that:
  383.    (1) since the input pixels (rather than the output pixels) are sharpened,
  384.        there is no false edge introduced when pixels are replicated.
  385.  
  386. The various processes described above are applied in the following order for
  387. pictures with fewer output pixels than input:
  388.    (a) scale,
  389.    (b) range or histogram equalisation,
  390.    (c) sharpen or smooth,
  391.    (d) error diffusion.
  392. This order is chosen so that:
  393.    (1) ranging can enhance down-sized images. Say a black/white dithered image
  394.        is reduced in size, so that the output from the scaling process is (some
  395.        approximation to) the original grey levels; then ranging can expand this
  396.        if possible.
  397.    (2) sharpening can be used to offset the blurring effects of scaling.
  398.    (3) since the output pixels (rather than the input pixels) are sharpened,
  399.        the effect of -sharpenN is consistent over differently scaled images.
  400.  
  401. There may be times when this automatic selection of order gets it wrong,
  402. particularly when changing the aspect ratio, it is possible to trigger some
  403. undesirable sharpening artifacts. Use the program twice with sharpening (say)
  404. disabled and enabled in the order required.
  405.  
  406. Examples of use:
  407.  
  408. Make "standard palette" versions of existing 256 colour images (for example
  409. the Watford digitiser plus colour board doesn't use the standard palette).
  410.   (e.g. "changefsi in out 13p" for a coloured Watford picture)
  411.  
  412. Or convert a colour picture to something you can see on your high res mono
  413. monitor.
  414.   (e.g. "changefsi in out 18 -sharpen -info")
  415.  
  416. Or convert a large monochrome picture (from a scanner, say) to something
  417. which can be seen.
  418.   (e.g. "changefsi in out 20t 1:4 -gamma")
  419.  
  420. Or convert a colour picture to grey scale for the desktop.
  421.   (e.g. "changefsi in out 20")
  422.  
  423. Or change a 512 by 480 image to standard format and aspect ratio
  424.   (e.g. "changefsi in out 15 640:512 512:480")
  425.   (or "changefsi in out = -range")
  426.  
  427. Or change to digital r, g, b
  428.   (e.g. "changefsi in out 20d -sharpen16")
  429.  
  430. Or convert a picture for printing on a 300dpi laser.
  431.   (e.g. "changefsi in out 18c 300:90 -sharpen")
  432.  
  433. And many more uses such as making miniatures of pictures, animated sequences of
  434. pictures changing size (or sharpness!), converting Artisan pictures to the
  435. desktop (try looking at the Artisan Garden with the desktop in 256 colours and
  436. ChangeFSI's version - the stripes on the lawn vanish with the standard
  437. version). Obviously you will need to have captured input as a sprite first!
  438. Using more pixels per inch can improve the quality of the result, particularly
  439. converting to multisync modes.
  440.  
  441. Note that, for all work with ChangeFSI, it is a good idea to start from the
  442. unprocessed input each time and do everything in one pass (rather than using
  443. the program several times with simple arguments). It is not a good idea to
  444. sharpen a dithered image (unless it has been shrunk). It can be very useful
  445. to use a small amount of smoothing on a dithered image (e.g. -smooth16).
  446.  
  447. *** It is a very good idea to keep the highest resolution master that you can
  448. afford the disc space for....
  449.  
  450. The ChangeFSI program can also convert from non RISC OS sprite formats while
  451. doing all of the above processing. ChangeFSI will work out what the format is
  452. automatically. For native RISC OS formats, it uses the filetype and there can
  453. be no confusion. For alien formats, it first tries looking for particular
  454. identifying information inside the file and then (if this fails to have
  455. identified a format) tries using the file name itself. See the details below:
  456.  
  457. The RISC OS sprite format
  458.  Contains 1, 2, 4 or 8 bits per pixel with a modification palette of up to
  459.  16 entries; any number of pixels wide and high uncompressed. Details are in
  460.  Acorn's Programmer's Reference Manual.
  461.  + Recognised by file type FF9 (a paint brush and house icon)
  462.  - Details of how many bits per pixel and the pixel size are obtained from
  463.    the operating system (rather than being in the file) from the "MODE"
  464.    number. Mode extensions can result in a source image containing a MODE
  465.    number which your computer does not understand.
  466.  - Mask information ignored
  467.  - Lefthand wastage ignored
  468.  
  469. The new RISC OS sprite format
  470.  Contains 1, 2, 4, 8, 16 or 32 bits per pixel.
  471.  + Recognised by file type FF9
  472.  + no problem with mode extensions: information is coded into the format
  473.  - Mask information ignored
  474.  
  475. Kodak PhotoCD
  476.  24 bit per pixel images at various resolutions
  477.  + Recognised by file type BE8
  478.  - Set ChangeFSI$PCDIndex to read resolutions other than base (=3)
  479.  
  480. The ArVis format [of ArVis Multimedia]
  481.  Contains 5 bits of red, green and blue information encoded into two RISC OS
  482.  sprites "HIP.<filename>" and "LOP.<filename>" comprising a 640 pixel wide
  483.  and 256 line tall image with pixels sized 1:2. Details from ArVis Multimedia
  484.  - Recognised by providing the HIP.<filename> (which must be of file type FF9)
  485.  - Uncompressed (indeed represents 16 bits instead of 15).
  486.  
  487. The Pineapple colour digitiser format (of Pineapple Software)
  488.  Contains 6 bits of green, 5 bits of red and blue information filed as a
  489.  single data file starting "FSIfile" comprising a 512 pixel wide and 256
  490.  line tall image with pixels sized 1:2.
  491.  - Recognised by "FSIfile" in the file (which can be any type)
  492.  - Uncompressed
  493.  
  494. The Watford Video Digitiser "picture" format
  495.  Contains a run length encoded 64 grey level 512 pixel wide, 256 line image,
  496.  with pixels sized 1:2. Details from Watford Electronics Ltd.
  497.  + Recognised by file type DFA (a small grey picture of Stevie Nicks)
  498.  - Warning: don't forget to save the pictures in *un-dithered* state!
  499.  When used with a colour converter, ChangeFSI can read three colour
  500.  separations stored in a directory of separate "red", "green" and "blue"
  501.  files. Beware of auto-gain/contrast when using such information!
  502.  
  503. The ProArtisan compressed picture file format
  504.  Contains a (mildly) compressed MODE 15 (640 by 256 by 256 colours) picture.
  505.  Details from Clares.
  506.  + Recognised by file type DE2 (a beige monitor in a grey surround)
  507.  
  508. The TimeStep satellite image format
  509.  This gives an uncompressed 800 by 800 with 256 grey levels.
  510.  + Recognised by file type 7A0 (icon never seen)
  511.  - No resolution specified, equal to mode 27 assumed
  512.  - Documentation never seen. An extra header file <name>! is not understood
  513.    at all.....
  514.  
  515. CCIR601 4:2:2 images
  516.  Contain 720 pixels by 288 rows (PAL) [243 rows NTSC] YUV coded with
  517.  pixels sized 1:2.
  518.  + Recognised by file type 601
  519.  - one field only
  520.  
  521. Another TimeStep satellite image format
  522.  Giving an uncompressed 128 pixels wide by 256 lines with 256 grey levels,
  523.  pixels sized 2:1. Used by TimeStep's !ImProcess application.
  524.  + Recognised by file type 300 ("i" in a document frame)
  525.  - Documentation never seen.
  526.  - A bit coarse
  527.  The grey levels represent intensity in various different wave bands. By
  528.  naming files "red", "green" and "blue" and handing ChangeFSI the directory,
  529.  you can produce a false colour image. Hours of experimentation can produce
  530.  an almost reasonable picture...
  531.  
  532. The AIM and Wild Vision V10 format
  533.  This provides an uncompressed 256 by 256 image with 256 grey levels. Details
  534.  from Delft University of Technology and ECD Computers Delft B.V.
  535.  + Recognised by file type 004 (a picture of 'Trui' with "TU" in blue)
  536.  + ChangeFSI can write to this format (specify "aim" in the mode position)
  537.    and specify = in the sizing to get a 256 by 256 output (otherwise it will
  538.    be the same size as the source image)
  539.  - No resolution specified, equal to mode 27 assumed
  540.  - The associated file <name>+ (file type 010) which contains additional
  541.    information is ignored by ChangeFSI.
  542.  The grey levels may represent intensity in various different wave bands. By
  543.  naming files "red", "green" and "blue" and handing ChangeFSI the directory,
  544.  you can produce a false colour image. Hours of experimentation can produce
  545.  an almost reasonable picture...
  546.  
  547. The Wild Vision V12 format
  548.  This provides an uncompressed 512 by 512 image with 256 grey levels.
  549.  + Recognised by file type 006
  550.  - No resolution specified, equal to mode 27 assumed
  551.  
  552. The Wild Vision V9 and SnapShot formats
  553.  This provides an uncompressed 512 by 256 image with 4 bits of red, green
  554.  and blue, pixels sized 1:2.
  555.  + Recognised by "MercSoft" or "SnapShot" header
  556.  + No file type needed
  557.  
  558. The !Translator Clear format
  559.  This provides 1, 2, 4, 8 and 24 bits per pixel.
  560.  + Recognised by file type 690
  561.  - uncompressed, especially for <8 bits per pixel which is recorded at one
  562.    byte per pixel.
  563.  - No resolution specified, equal to mode 27 assumed
  564.  
  565. The Atari ST "Degas" format
  566.  1, 2 or 4 bits per pixel, clear or run length encoded. RISC OS file type by
  567.  John Kortink of !Translator.
  568.  + Recognised by file type 691
  569.  - No documentation and only 5 images read
  570.  - No resolution specified, equal to mode 27 assumed
  571.  
  572. >> All the file formats so far have been designed on RISC OS (or Arthur) and
  573. recognition of the format is defined by file type, the files arrive on RISC
  574. OS floppy discs, and the originators live in the same time zone. For the
  575. following formats many of these things are not true... Which makes it more
  576. difficult to guarantee that ChangeFSI will be able to read the file.
  577.  
  578. The Millipede Prisma format (used by CadSoft also)
  579.  The Millipede Prisma 3 is a 768 pixels wide by 574 line interlaced display
  580.  board for the Archimedes and BBC Microcomputer. It allows use of 256
  581.  colours from 2^24. Files may be stored uncompressed (432KBytes!) or run
  582.  length encoded. More details from CadSoft or Millipede Electronic Graphics.
  583.  + Recognised by "MILLIPEDE" at offset 16 in the file
  584.  - No resolution specified, equal to mode 27 assumed
  585.  - slowish to read the compressed formats
  586.  - scaling the picture using = can be poor since 574 lines don't relate very
  587.    well to 512 or 256. Use -info to display the scale ratios.
  588.  
  589. The Aldus/MicroSoft TIFF format (also filetype FF0 is assigned to TIFF)
  590.  Frequently used by scanners, TIFF is a common interchange format for
  591.  graphics images on the Mac and PC (particularly DTP and Windows). It
  592.  provides an arbitrary number of bits per pixel, size etc using a numeric tag
  593.  scheme allowing new information to be introduced without upsetting existing
  594.  programs. The format may be compressed (in 5 different ways at present).
  595.  Details from Aldus UK, MicroSoft, Hewlett Packard...
  596.  + Recognised by file type FF0
  597.  + Recognised by "II" plus the 16 bit number 42 at the start of the file for
  598.    little endian machines (ix86, ARM, VAX...)
  599.  + Recognised by "MM" plus the 16 bit number 42 at the start of the file for
  600.    big endian machines (M680x0...)
  601.  + Can read PackBits images and LZW compressed forms (at least the 3 its
  602.    seen so far...)
  603.  - Cannot read predictor compressed LZW images.
  604.  - So far ChangeFSI has only done 1, 4, 8 and 24 bit images.
  605.    It can't read "planar" images or CCITT compressed forms.
  606.  - Some TIFF images have incorrect pixel sizes: use -nosize if this is
  607.    true. If no pixel size is specified, ChangeFSI assumes mode 27 size.
  608.  + TIFF is a trademark of Aldus Corporation
  609.  
  610. The CompuServe GIF format
  611.  Used for wide area network transfer of images. It provides an LZW
  612.  compressed up to 256 colours from 2^24 arbitrary sized image. Details from
  613.  CompuServe (USA) [or usenet]
  614.  + Recognised by "GIF8" at the start of the file
  615.  + LZW compression is efficient even for dithered images
  616.  + ChangeFSI can decompress LZW quickly
  617.  - No resolution specified, equal to mode 27 assumed
  618.  - many low quality images around from PCs
  619.  - no processing of GIF89a masks
  620.  
  621. The Electronic Arts IFF ILBM format
  622.  Provides an arbitrary sized image with up to 4096 colours sometimes run
  623.  length encoded. ChangeFSI understands the generic format and also the
  624.  special Amiga format for "HAM" and "Half-bright" images.
  625.  + Recognised by "FORM" as the first four characters and "ILBM" as
  626.    characters 8 to 11
  627.  - Only pixel aspect ratio specified, not its size (and then sometimes
  628.    incorrectly): use -nosize *and* a size change (a:b) if its wrong
  629.  - images often small
  630.  - doesn't understand Amiga "hires"
  631.  - can't convert HAM pictures directly to monochrome
  632.  
  633. The MicroSoft Windows 3 .BMP format
  634.  Used by MicroSoft in Windows 3 and PaintBrush for Windows 3. Provides an
  635.  arbitrary sized image and 1, 4 or 8 bits per pixel. Uncompressed.
  636.  + Recognised by "BM" as the first two characters
  637.  - No resolution specified, equal to mode 27 assumed
  638.  - documentation never seen - 7 files examined and intelligent guesses made!
  639.  
  640. The Digital Research GEM .IMG format
  641.  Used by GEM (and GEM Paint) on both PC and Atari ST. Provides an arbitrary
  642.  sized image and number of bits per pixel (though its only usually used with
  643.  up to 5 bits per pixel) and pixel size. Compressed by run length encoding
  644.  and line repeats.
  645.  - Recognised by 00 01 00 08 as the first four bytes ("version 1, header
  646.    length 8") or by "IMG" as the name of the directory the file is in.
  647.  - Planar file format slow to read
  648.  - Palette not specified: ChangeFSI assumes linear shades of grey. You might
  649.    need to use -invert if the image is a negative
  650.  - The size of a pixel is specified in microns. The standard RISC OS 90
  651.    pixels per inch translates to (1/90*2.54*10,000) microns - 282. (use
  652.    -info to get information about the scaling, -nosize to stop it)
  653.  - Documentation from the "ST World" magazine's clinic.
  654.  
  655. An unknown PC .PIC format
  656.  Used for some VGA demos, the format provides an uncompressed 320 by 200 by
  657.  256 colour (from 2^24) VGA screen dump.
  658.  + Recognised by "AV_VO" as the first five bytes in the file
  659.  - Documentation never seen
  660.  - Pixel size assumed the same as MODE 13 (45 pixels per inch).
  661.  
  662. The MacPaint format
  663.  Provides a 576 by 720 bitmap, run length coded by the Mac's "PackBits"
  664.  algorithm (repeated bytes).
  665.  - Recognised by "PNTG" at position 65 in the file. This may only relate to
  666.    files which have been through a program called "MacFix". Data assumed to
  667.    start at position 128 in the file. Header ignored.
  668.  - No resolution specified, equal to mode 25 assumed
  669.  
  670. The Mac PICT2 format (PICT extended version 2)
  671.  Provides an arbitary size packed picture, run length coded by the Mac's
  672.  "PackBits" algorithm (repeated bytes).
  673.  + Recognised by looking for the PICT header at position 514 in the file.
  674.    The header is 00 11 02 FF 0C 00 FF FE.
  675.  - Documentation available but mostly useless (it assumes you are about to
  676.    call QuickDraw routines - "Note: for maximum safety and convenience, let
  677.    QuickDraw generate and interpret your pictures." Apple fail to describe
  678.    the PackBits algorithm in Inside Mac...)
  679.  - PICT is the loose equivalent of RISC OS Draw file format, but without
  680.    the explicit sizing of objects - for PICT, if there is an object that
  681.    you don't understand, there's no way of skipping it (whereas for Draw,
  682.    the size of the object is specified in an object indep. way). Apple
  683.    present a large table of the sizes of the objects (0000 - FFFF) which is
  684.    not in ChangeFSI. Consequently, if ChangeFSI finds an object it doesn't
  685.    know about before the picture, it stops...
  686.  - Only PackBitsRect (0098) (8bpp) and DirectBitsRect (009A) (24/32 bpp) are
  687.    allowed.
  688.  + ChangeFSI tries to skip a Clip (0001) region if it encounters it, since it
  689.    is hard to get the Mac OS to make PICT files without a clip opcode in them.
  690.  + size of pixel specified.
  691.  - Only 3 pictures read - since the format is very complicated (e.g. the size
  692.    of things change if >250 rows in the picture!) this is no guarentee that
  693.    anything else will be right.
  694.  
  695. The ZSoft .PCX format
  696.  Used by PC Paintbrush. Usually a 4 bit per pixel image (CGA, EGA, VGA) but
  697.  can be 1-8 bits per pixel.
  698.  - Recognised by 10,[0,2,3,4,5],1 at start of file. Or by name PCX.<foo>. Or
  699.    by type &697.
  700.  + Intelligent check for resolution of the DACs on the PC card. Use -info to
  701.    find out what ChangeFSI thinks it is.
  702.  + Pixel size information read. You may need to stop the scaling with
  703.    -nosize, since its often wrong.
  704.  
  705. The RIX Softworks ColoRIX format
  706.  Used by VGA Paint, image extension .SCE .. .SCX. 4 or 8 bits per pixel.
  707.  - Recognised by "RIX3" at start of file
  708.  - Documentation never seen
  709.  - Only 5 files read: ChangeFSI checks to see if the header is the same
  710.    as these files and complains otherwise.
  711.  - No resolution specified, equal to mode 27 assumed
  712.  
  713. The Sun "pixrect" format
  714.  Used under SunOS and also under X11. Commonly 1 or 8 bits per pixel, but up
  715.  to 24 bits per pixel can be found (see the Sun NeWS release tape!).
  716.  + Recognised by &59A55A95 at the start of the file.
  717.  - No resolution specified, equal to mode 27 assumed
  718.  - Sun didn't specify the pixel ordering of 24 bit per pixel images: many
  719.    assume RGB when it was actually BGR. Change byte &17 in the Sun
  720.    rasterfile between 1 and 3 if you have a problem.
  721.  
  722. The "pbm" 'portable bitmap' file format
  723.  Used by the "PBM-PLUS" toolkit (mainly Unix) by Jef Poskanzer. 1-24 bits
  724.  per pixel (more can be specified in the format but ChangeFSI cannot read
  725.  them). ChangeFSI can only read the "RAWBITS" formats (it can write all of
  726.  the pbm formats).
  727.  + Recognised by P4/P5/P6 at start of file.
  728.  + Writable by ChangeFSI
  729.  - No resolution specified, equal to mode 27 assumed
  730.  
  731. The UNIX "rle" format
  732.  Used by a program called "svfb" to save the contents of large frame
  733.  buffers, checked with four images at 24 bits per pixel.
  734.  + Recognised by &CC52 at the start of the file.
  735.  - No resolution specified, equal to mode 27 assumed
  736.  
  737. The TrueVision Targa format
  738.  Used by TrueVision for Vista boards. Up to 32 bits per pixel.
  739.  - Recognised by suffix _TGA or _VDA on the name. Or by type &69d.
  740.  - Only uncompressed formats readable.
  741.  - Only 8 and 16 bit per pixel formats tested.
  742.  
  743. The "Flexible Image Transport System" (FITS) format
  744.  Used for astronomical data. Up to 16 bits per pixel component.
  745.  + Recognised by "SIMPLE" at the start of the file.
  746.  - Only 8 and 16 bit per pixel component formats tested.
  747.  - Only two files ever seen!
  748.  - No resolution specified, equal to mode 27 assumed
  749.  
  750. The Irlam instruments colour scanner format
  751.  24 bit per pixel from colour scanner.
  752.  + Recognised by Irlam 24 at the start of the file.
  753.  + Writable by ChangeFSI
  754.  - No resolution specified, equal to mode 27 assumed
  755.  - may need gamma correction
  756.  
  757. The Irlam instruments YUV 411 colour video format
  758.  7 bits Y, up to 7 bits U and V.
  759.  + Recognised by Irlam YUV 411 at the start of the file
  760.  - no resolution specified, equal to mode 27 assumed
  761.  
  762. The JPEG 'JFIF' File Interchange Format
  763.  Up to 24 bits R,G,B, compressed by the JPEG compression system.
  764.  + Recognised by JFIF at position 6 in the file (you may have to
  765.    cut headers off files, particularly if they are from Macs).
  766.  + Often highly compressed
  767.  + If ChangeFSI$Cache is large enough (bigger than the file), then high
  768.    speed routines are used to decompress. Otherwise:
  769.  - ChangeFSI calls a djpeg routine. This can be on the Run$Path, implemented
  770.    as an Alias (in which case it *must* use WimpTask to start) or found
  771.    inside ChangeFSI$Dir if all else fails. cjpeg (the compressor) is also
  772.    available inside ChangeFSI$Dir - you will need to convert the image to
  773.    P6 format before it can be compressed. Djpeg and cjpeg are by the
  774.    PD JPEG group.
  775.  - ... and therefore slow. Needs a lot of space in <Wimp$Scrap>.
  776.  - no resolution specified, equal to mode 27 assumed
  777.  
  778. The Ronald Alpiar 36 and 48 bit per pixel formats
  779.  12 and 16 bits for each of R,G,B, uncompressed
  780.  + Recognised by ALPIAR12 or ALPIAR16 at start of file
  781.  + followed by little endian word of X size and word of Y size
  782.  + followed by r,g,b as little endian half words
  783.  - no resolution specified, equal to mode 27 assumed
  784.  
  785. The btpc file format
  786.  Up to 24 bits R,G,B, compressed by the btpc compression system
  787.  + Recognised by btpc at start of the file
  788.  + Highly compressed (sometimes more than JPEG)
  789.  - ChangeFSI calls a (slow) dbtpc routine
  790.  - no resolution specified, equal to mode 27 assumed
  791.  
  792. >> The following file formats are only recognised by their names.
  793.  
  794. An unknown PC .DSP format
  795.  Experimentally determined that it holds a 640 by 350 EGA picture at 4 bits
  796.  per pixel. ChangeFSI "knows" the default EGA palette (from IBM literature).
  797.  - Recognised by being in a directory "DSP"
  798.  - Documentation never seen
  799.  - No resolution specified, equal to mode 27 assumed
  800.  - Only two examples read(!)
  801.  
  802. The QRT .raw format
  803.  Output from Steve Koren's public domain ray tracer: arbitrary size in 2^24
  804.  colours, uncompressed. Documentation part of QRT.
  805.  - Recognised by the name ending ".Raw". Or by type &698.
  806.  - No resolution specified, equal to mode 27 assumed
  807.  
  808. The MTV pic. format
  809.  Output from Mark Terrence VandeWettering public domain ray tracer arbitrary
  810.  size in 2^24 colours, uncompressed. Documentation part of MTV. Also used by
  811.  "RayShade".
  812.  - Recognised by being in a directory "Pic.". Or by type &699.
  813.  - No resolution specified, equal to mode 27 assumed
  814.  
  815. The RT image. format
  816.  Output from "RT", a private ray tracer by Brian D Watt(?) arbitrary size in
  817.  2^24 colours, run length encoded.
  818.  - Recognised by being in a directory "Image."
  819.  - No resolution specified, equal to mode 27 assumed
  820.  
  821. For many of these formats, especially the uncompressed ones, setting the
  822. variable "ChangeFSI$Cache" to the number of bytes of temporary memory you
  823. wish the program to use will speed up reading the information. The default
  824. is 49152 bytes. For example "*set ChangeFSI$Cache 80k". For those worried
  825. about speed, the program will go faster if:
  826.  
  827.  - you use -noscale and keep 1:1 ratios (don't specify them)
  828.    (although -nosize and 1:1 or 1:2 ratios are quick, too)
  829.  - you don't need sharpening/smoothing, histogram equalisation, range expansion
  830.  - you use monochrome (e.g. 25, 26, 27 and 27t) modes
  831.  
  832. additionally you can disable dithering (-nodither) especially when reading
  833. monochrome source.
  834.  
  835. You can avoid the program changing mode by putting -nomode on the command line.
  836.  
  837. Very large output files can be built strips at a time and sent directly to disk
  838. using the parameter "-max" e.g:
  839.  
  840.   ChangeFSI <in> <out> 28 -max512K
  841.  
  842. will convert the file with a maximum of 512KBytes held in memory. Options 25t,
  843. -rotate and -vflip don't work when this is being done.
  844.  
  845. Work will be done on other formats when and if both image and documentation
  846. arrive at Acorn. Adding a new format is a matter of (a) putting in automatic
  847. recognition of the format at the start of the program (b) reading the size of
  848. the image and the colour palette mapping [in the next section of the program]
  849. (c) writing a "read pixel row" element inside PROCiprow (d) providing an entry
  850. in PROCrewind. If you write a new format interface, please send it to me so
  851. that it will be included in later versions. ChangeFSI has already got code for
  852. dealing with images with 1, 2, 4 and 8 bits per pixel packed into bytes and for
  853. images with up to 8 bit planes. There is support code for LZW decompression and
  854. LZW decoding.
  855.  
  856. As a special feature, ChangeFSI will also write out 256 grey level files (alter
  857. rwt, gwt and bwt to get 256 level colour separations) in AIM format. This is
  858. file type 4 with bytes representing the grey level. Use the = operation to
  859. restrict the picture to 256x256y, otherwise it will be the same size as the
  860. input. Specify "aim" as the mode string to do this.
  861.  
  862. For portability to other machines, ChangeFSI can write out files in "pbm"
  863. format. There are 3 types of format "black/white" (pbm), "grey" (pgm) and
  864. "colour" (ppm) with pure ASCII and binary encodings of each:
  865.  
  866. ASCII                                   Binary
  867. p1        "black/white" (like mode 18)  p4 (big endian bytes!)
  868. p2        "grey" (like mode 20t)        p5
  869. p3        "true colour"                 p6
  870.  
  871. Files can be read with Jef Poskanzer's portable toolkit on other machines. The
  872. p2 format is easily convertible by programmers; it consists of:
  873.  
  874. P2
  875. # comment line
  876. xsize ysize
  877. maximum_value
  878. pixel_value <whitespace> pixel_value
  879.  
  880. where all the numbers are in decimal (ASCII). 0 means black, maximum_value (=
  881. 15) means white. The p3 format is similar with r, g, b triples for each pixel
  882. value. The number of bits per component (default 8) can be set from the command
  883. line with, for example, "p3,4" for 4 bits per component.
  884.  
  885. As a special packed output format, "P15" has been implemented. Output is binary
  886. pixel values, 5 bits per component, little endian RGB order packed into 16
  887. bits. Header information as the other p formats.
  888.  
  889. Files can be written as new RISC OS sprites using S16 and S32 as the formats.
  890. The x and y pixels per inch are given as a comma seperated list - a 16 bit mode
  891. 12 equivalent is S16,90,45 while a 32 bit mode 28 equivalent is S32,90,90.
  892.  
  893. Files can be written as JPEG images using JPEG (colour) or JPEGMONO. A quality
  894. in the range 1 to 100 must be added to the end (e.g. JPEG75 or JPEGMONO50).
  895.  
  896. ChangeFSI can write Irlam format images (somewhat slower than p6 images...).
  897.  
  898.                               Output summary
  899.                               ==============
  900.  
  901. # cols   Colour Cube  Bits used  Consistent Hue  Desktop Palette  Mode&Suffix
  902.  
  903. 2^24            Y         24           Y             -            S32, p3 or p6 or Irlam or JPEG
  904. 2^21            Y         21           Y             -            p6,7
  905. 2^18            Y         18           Y             -            p6,6
  906. 2^15            Y         15           Y             -            S16, p15 or p6,5
  907. 2^12            Y         12           Y             -            p6,4
  908. 512             Y          9           Y             -            p6,3
  909. 256 grey        n          8           Y             -            aim or JPEGMONO
  910. 256 grey        n          8           Y             -            28d
  911. 256             Y          8           Y             Y            28
  912. 256             Y          8           Y             Y            28r
  913. 16 grey         n          4           Y             n            27t
  914. 16 grey         n          4           Y             n            p2 or p5
  915. 8 grey          n          3           Y             Y            27
  916. 16              ?          4           ?             Y            27r
  917. 16              Y          3           Y           can be         27d
  918. 4 grey          n          2           Y             Y            26
  919. 4               n          2           n             n            26c
  920. 4               n          2           n             n            26r
  921. 2 (black/white) n          1           Y             Y            25
  922. 2 (black/white) n          1           Y             Y            25c/d/t
  923. 2 (black/white) n          1           Y             Y            p1 or p4
  924.  
  925.  
  926. ChangeFSI can be used from both the desktop front end and from the command
  927. line. It can also be used as a BASIC library function:
  928. LIBRARY"<ChangeFSI$Dir>.ChangeFSI" gives a new function, FNChangeFSI to the
  929. BASIC programmer. This function takes:
  930.   A$: a command line argument
  931.   spritearea%: an address or -1 for the spritearea built by ChangeFSI
  932.   workspace%: an address or -1 for ChangeFSI's other workspace
  933.   worklimit%: an address (unused if workspace%<0)
  934.   fast%: TRUE for MODE 0 selection
  935. It produces an error (to whatever error handler is present) if it fails. If
  936. spritearea% is <0 it will save the sprite to the file given in the command
  937. string, otherwise it won't. The function FNChangeFSIVersion returns the version
  938. string of the library (in the info box of the desktop application).
  939.  
  940.                            Command Summary
  941.                            ===============
  942.  
  943. -info     give details
  944.  
  945. -hist     don't process image, but display histogram of it instead
  946.  
  947. -hflip    horizontally flip the image
  948. -vflip    vertically flip the image
  949. -rotate   rotate the image by +90 degrees (i.e. anti-clockwise)
  950. -rotate-  rotate the image by -90 degrees (i.e. clockwise)
  951. -max      set the maximum size of the image before disc is used
  952.  
  953. -noscale  disable automatic pixel size correction
  954. -nosize   disable automatic pixel size correction for input pixels only
  955. -nodither disable dithering
  956. -nomode   don't change to mode 0 while processing the picture
  957. -invert   invert colour range of image
  958.  
  959. -range    expand input's dynamic range to full scale
  960. -equal    histogram equalisation
  961. -sharpen  digitally sharpen the picture
  962. -smooth   digitally smooth the picture
  963.  
  964. -gamma    set gamma correction
  965. -black    correct for black ink spot size
  966. -red      change red weight for deriving monochrome luminance
  967. -green    change green weight for deriving monochrome luminance
  968. -blue     change blue weight for deriving monochrome luminance
  969.  
  970. -brighten horrendous hack to slightly brighten images: may convert hues
  971.           close to white to white. (It causes the output range 0..15 to
  972.           be considered as 0..(15/16) instead of 0..(15/15)).
  973.  
  974.                            Mode Suffixes
  975.                            =============
  976.  
  977. c
  978.   1 bit modes: use clustered dithering with 4x4 cell
  979.   2 bit modes: use the four colours "black", "cyan", "magenta" and "yellow"
  980. d
  981.   1 bit modes: use clustered dithering with 2x2 cell
  982.   4 bit modes: use 1 bit red, 1 bit green, 1 bit blue
  983.   8 bit modes: use 256 level grey scale
  984. t
  985.   1 bit modes: use clustered dithering with 3x3 cell
  986.   4 bit modes: 16 level grey scale
  987. r
  988.   2 bit modes: Devious colour matching algorithm
  989.   4 bit modes: Devious colour matching algorithm
  990.   8 bit modes: Devious colour matching algorithm
  991. -no suffix-
  992.   1 bit modes: b/w dispersed dot dithering
  993.   2 bit modes: 4 level grey scale
  994.   4 bit modes: 8 level grey scale
  995.   8 bit modes: John Bowler's colour matching algorithm
  996.                (defaults to 'r' mode if not VIDC1 compatible)
  997.  
  998. Colour matching is done in r, g, b space: the minimum distance between colours
  999. is the square root of:
  1000.    delta_r^2*rmatchwt+delta_g^2*gmatchwt+delta_b^2*bmatchwt
  1001. ChangeFSI has hard wired weights of 3, 10, 1 respectively for its colour
  1002. matching algorithms. John Bowler's algorithm (default for RISC OS 8 bit modes)
  1003. although somewhat slower, is fast enough to have replaced all the previous
  1004. methods [ASIDE it gives pictures at least as good as "p" mode in pre Aug 91
  1005. ChangeFSI's]. The Devious colour matching algorithm is recommended, and is
  1006. used automatically if the 8 bit per pixel mode does not have the default RISC
  1007. OS colour set.
  1008.  
  1009. [NOTE: thanks are due to Steve Green and the BBC and Irlam Instruments for
  1010. the intermediate systems that led to John Bowler's and the Devious
  1011. algorithms: until Aug 91 ChangeFSI used their work for its "Precise
  1012. Matching" algorithm. It no longer uses any of their code, but owes a debt
  1013. for overall approach. A small thank you to Spencer Thomas for putting me on
  1014. the track which led to the Devious colour matching system's algorithm.]
  1015.  
  1016. Further information on dithering can be found in "Digital Halftoning" by Robert
  1017. Ulichney published by the MIT Press, ISBN 0-262-21009-6. A book which would have
  1018. been useful when starting writing the program, rather than after it was nearly
  1019. finished! Histogram equalisation is in "Algorithms for Graphics and Image
  1020. Processing" by Theo Pavlidis published by Computer Science Press, ISBN
  1021. 0-914894-65-X.
  1022.