>>>    DOWNLOAD FAB v0.3    <<<

Florian & Alain's Blender. fab v0.3: A command line tool to create and manipulate images.

1. Command line? 2. File formats 3. List of commands.    3.1. File conversion    3.2. Drawing primitives    3.3. Standard image manipulation    3.4. Arithmetic and logic functions    3.5. Sampling et scaling functions    3.6. Standard color manipulation    3.7. Color dithering    3.8. Convolution filter    3.9. Misc functions 4. Some examples 5. Future

1. Command line?

fab is a command line tool to create and manipulate images. This means there is no graphical user interface (gui) and you must execute the fab program with parameters so that it will perform operations on the image files. To give commands and parameters to the program, the first method is to open a command line interpreter (command prompt on m$do$, cli on RiscOS, shell on Unixes...) and write your orders one after another. For example on m$do$:
(niko_heart.bmp)

  C:\baah\c\fab>fab bmp2rgb niko_heart.bmp red.g green.g blue.g
  bmp2rgb: 32 x 32 OK
  C:\baah\c\fab>fab rgb2bmp green.g blue.g red.g niko_heart_blue.bmp
  rgb2bmp: 32 x 32, 11 colors OK

The second method is to make a file with the different commands and ask the system to execute them (batch file on m$do$, obey file on RiscOS, shell file on Unixes...). For the example above, again of m$do$, you create a text file called "example.txt", write the following orders in it:

  fab bmp2rgb niko_heart.bmp red.g green.g blue.g
  fab rgb2bmp green.g blue.g red.g niko_heart_blue.bmp
  del *.g

2. File formats

fab uses the following fileformats:

• The classical .bmp bitmap format from m$window$ is widely known and simple enough to exist in almost every graphic program. It can support images up to 16,777,216 colours (24 bits per pixel). There are only two functions dealing with .bmp files, because fab only performs graphical operation on .g files.
• The .g files are containing only one channel of an image: red or green or blue values, or grey values or... Sometimes you'll need to perform operations three times, one for each channel. A .g file contains two 16 bits numbers for width and height of an image, then width*height values for the channel, each one being a 16 bits number. So theoretically we can go up to 281,474,976,710,656 colours (48 bits per pixel).
• The .pal files are containing colour palettes. They are made of triplets of bytes, one for every colour. There's only one operation using this.
• A palette can also be given as a .txt file, which shall contain the palette in hexadecimal format, 6 chars per palette entry (so 0 shall be coded as 00). Chars not in the [0;9]+[A;F] range are ignored. Also, if a line contains a semicolon, the rest of the line is treated as a comment.
• It's also possible to save an image in an Atari ST like bitplane format.

3. List of commands

Commands and parameters are shown in bold. Comments are in normal text. Functions that might be added in the future are shown between interrogation marks.

3.1. File conversion

• fab bmp2rgb in.bmp red.g green.g blue.g
• fab rgb2bmp red.g green.g blue.g out.bmp
• fab palette2rgb in.pal in.g red.g green.g blue.g // assigns pixels according to a color palette file
• fab textpalette2rgb in.txt in.g red.g green.g blue.g // same as above, but color palette is given in hexadecimal text
• fab grey2bitplanes nbbitplanes in.g out.xxx // save a grey image in the Atari ST bitplanes mixed format (was used for mkstrippedtube)

3.2. Drawing primitives

The bottom left corner has coordinates (0;0).

• fab mknoise colormin colormax width height out.g // creates an image filled with noise. I often use it to create an empty image (colormin=colormax=0)
• fab disc xcenter ycenter radius color in.g out.g
• fab rectangle xleft ybottom xright ytop color in.g out.g
• fab rectangle2 xleft ybottom width height color in.g out.g

3.3. Standard image manipulation

• fab negative in.g out.g // BEWARE, pixel=65535-pixel, maybe rsbI 255 is what you want
• fab rgb2grey red.g green.g blue.g grey.g // grey=(red+green+blue)/3
• fab rotate90 in.g out.g // clockwise
• fab rotate180 in.g out.g
• fab rotate270 in.g out.g
• fab hmirror in.g out.g // image upside down
• fab vmirror in.g out.g
• fab addborders left right up down color in.g out.g
• fab removeborders left right up down in.g out.g
• fab autosetborders width in.g out.g
  Check if a border colors exists (there must be at least one border with a unique color, and all borders with unique color share the same one) then modifies the image so that all borders have the same width (possibly 0).

3.4. Arithmetic and logic functions

• fab add in1.g in2.g out.g
• fab sub in1.g in2.g out.g
• fab mul in1.g in2.g out.g
• fab div in1.g in2.g out.g // in1.g is divided by in2.g
• fab and in1.g in2.g out.g
• fab or in1.g in2.g out.g
• fab xor in1.g in2.g out.g
• fab addI value in.g out.g // same as above but with an Immediate value
• fab subI in.g value out.g
• fab rsbI value in.g out.g // rsb means reverse substract
• fab mulI factor in.g out.g
• fab divI in.g divisor out.g
• fab rdvI dividend in.g out.g //rdv means reverse divide
• fab andI value in.g out.g
• fab orI value in.g out.g
• fab xorI value in.g out.g

Arithmetic and logic functions can be used for many purposes. One of them is putting an image above another, as explained below:

step 1: background image (blurred random noise on R/G/B channels)
step 2: sprite (ie image to put above the other one)
step 3: mask for sprite (pixels in sprite set to 0, others set to 255)
step 4: background AND mask
step 5: (background AND mask) OR sprite

You can also have smoother edges for the sprite if its mask contains more than on/off information. Below the mask has been blurred (using a convolution filter). The sprite is modified with "(sprite MUL mask) DIV 255", and we also replace step 4 above by "(background MUL mask) DIV 255".

3.5. Sampling et scaling functions

• fab sampleup_miller nbiterations in.g out.g // size will be multiplied by 2^nbiterations
  Each iteration goes like this: for every pixel h(x;y) you take h00=h(x+0;y+0); h01=h(x+0;y+1); h10=h(x+1,y+0); h11=h(x+1;y+1) and you create 4 points:
  h(x+0.25;y+0.25)=0.75*0.75*h00+0.75*0.25*h01+0.25*0.75*h10+0.25*0.25*h11
  h(x+0.75;y+0.25)=0.25*0.75*h00+0.25*0.25*h01+0.75*0.75*h10+0.75*0.25*h11
  h(x+0.25;y+0.75)=0.75*0.25*h00+0.75*0.75*h01+0.25*0.25*h10+0.25*0.75*h11
  h(x+0.75;y+0.75)=0.25*0.25*h00+0.25*0.75*h01+0.75*0.25*h10+0.75*0.75*h11
  The old pixels are forgotten. The computations are in fact very easy since 0.75*0.75=9/16, 0.75*0.25=3/16 and 0.25*0.25=1/16.
• fab sampledown xratio yratio in.g out.g // xratio and yratio must be integers
• fab scaleup xratio yratio in.g out.g
• fab scaledown xratio yratio in.g out.g

3.6. Standard color manipulation

• fab setmincolor newmincolor in.g out.g // substract oldmincolor-newmincolor to every pixel
• fab setmaxcolor newmaxcolor in.g out.g // substract oldmaxcolor-newmaxcolor to every pixel
• fab allcolorsabove mincolor in.g out.g // if color<mincolor then color=mincolor
• fab allcolorsbelow maxcolor in.g out.g // if color>maxcolor then color=maxcolor
• fab allcolorsbetween mincolor maxcolor in.g out.g // if color<mincolor then color=mincolor, etc
• fab range mincolor maxcolor in.g out.g // = equalise???

3.7. Color dithering

The output of all this functions will be a grey image with intensity in [0;nb_colors-1]. You'll often use the range function afterward to put the intensity back in [0;255]. Also note that you must use the range function to make nearest neighbourg ordering.

• fab ordered2x1 nb_colors in.g out.g // vertical lines
• fab ordered1x2 nb_colors in.g out.g // horizontal lines
• fab ordered2x2 nb_colors in.g out.g //(also called Bayer algorithm???)
• fab ordered3x3 nb_colors in.g out.g
• fab ordered4x4 nb_colors in.g out.g
• fab ordered4x4bis nb_colors in.g out.g // diagonals
• fab floydsteinberg nb_colors in.g out.g // reduce colors using Floyd-Steinberg algorithm, which propagates the error made on current pixel to the next ones with following coefficients:

      . 7
    3 5 1

• fab stucki nb_colors in.g out.g // another error diffusion algorithm, which is said to have a clean and sharp output. The idea is similar to Floyd-Steinberg but with the following coefficients:

        . 8 4
    2 4 8 4 2
    1 2 4 2 1

The image below shows a texture (fractal landscape with modulo) with colors reduced using nearest neighbourgs (range 0 1 in.g out.g) and all ditherings above:

???fab ordereddithering + page flip => 5+4=9 grey levels???
???fab floyd palette.pal red.g green.g blue.g out.g // <65536 colors???
* There are many ways to find the nearest palette color with varying levels of efficiency and quality. A trivial algorithm is to search the color with minimum straight line distance in the color cube from the given color.
* We can alternate between left-to-right and right-to-left (also reflect the diffusion matrix), this avoids some kind of artifacts.

3.8. Convolution filter

Only one function in here, but it's an important one since it can be used for a lot of effects.

• fab filter a b c d e f g h i n offset in.g out.g // applies a convolution filter with the surrounding pixel. You control the effect by giving a 3x3 matrix (a to i) which is used to multiply the value of the current pixel (in the center) and its neighbourgs, all this is summed up and divided by n. Finally we add an offset. The matrix is shown below:

      (a b c)
      (d e f) :n + offset 
      (g h i)

Some usefull filters:
fab filter 0 1 0 1 1 1 0 1 0 5 0 in.g out.g // smooth1
fab filter 1 2 1 2 4 2 1 2 1 16 0 in.g out.g // smooth2
fab filter -1 1 -1 1 1 1 -1 1 -1 1 0 in.g out.g // unsmooth
fab filter -2 -1 0 -1 0 1 0 1 2 1 128 in.g out.g // relief1
fab filter -1 1 -1 1 0 1 -1 1 -1 1 128 in.g out.g // relief2
fab filter 0 -1 0 -1 2 0 0 0 0 1 128 in.g out.g // relief3
fab filter 1 0 1 0 -1 0 1 0 1 3 0 in.g out.g // strange1
fab filter 0 1 0 1 -1 1 0 1 0 3 0 in.g out.g // strange2
fab filter 0 -n 0 -n 4n+1 -n 0 -n 0 1 0 in.g out.g // sharpness
fab filter -n -n -n -n 8n+1 -n -n -n -n 1 0 in.g out.g // sharpness2
fab filter -1 -1 -1 -1 8 -1 -1 -1 -1 1 0 in.g out.g // edge=laplace
fab filter 0 -1 0 -1 4 -1 0 -1 0 1 0 in.g out.g // laplace2
fab filter -1 -1 -1 0 0 0 1 1 1 1 0 in.g out.g // edge2
fab filter -5 0 0 0 0 0 0 0 5 1 0 in.g out.g // edge3
fab filter 0 0 0 0 -1 0 0 0 1 1 0 in.g out.g // emboss
fab filter 2 0 0 0 -1 0 0 0 -1 1 0 in.g out.g // emboss2
fab filter -2 -1 0 -1 1 1 0 1 2 1 0 in.g out.g // repoussage

3.9. Misc functions

fab allows for easy implementation of graphical routines. The ones below are less classical, but might be of interest.

• fab fillwithOs OutRMin OutRMax InRMmin InRMmax Border ClearColor CircleColor in.g out.g // if you set ClearColor to 0, then you can have circles inside circles
  //Border is the gap between neighbouring circles, i usually set it to 0
• fab edge size emptycolor edgecolor in.g out.g // creates an edge around non empty pixels
• fab explode nbpoints in.g out.g// moves randomly nbpoints points
• fab landscape nbiterations in.g out.g // fractal landscape, used for many textures
• fab mkstrippedtube diameter nbsteps nbstripes col0 col1 out.g // this one was made to create a tube for an Atari ST demo.

4. Some examples

To make a shadow, we get two shifted copies of the same image, we enlighten (or darken) the shadow with range, blur it with filter and then put the original image above:

fab bmp2rgb fab_1bpp.bmp shape.g shape.g shape.g fab rsbI 255 shape.g shape.g rem Now the logo is set to 0, outside to 255 fab addborders 10 0 10 0 255 shape.g shadow.g fab range 160 255 shadow.g shadow.g fab filter 1 2 1 2 4 2 1 2 1 16 0 shadow.g shadow.g fab filter 1 2 1 2 4 2 1 2 1 16 0 shadow.g shadow.g fab addborders 0 10 0 10 255 shape.g shape.g fab and shape.g shadow.g shape.g rem Since shape.g contains only 0 and 255 values, rem a simple "and" had the same effect as masking fab sampledown 2 2 shape.g shape.g fab rgb2bmp shape.g shape.g shape.g TutorialShadow.bmp del *.g

Many textures are in the examples folder, i'll just speak about Txtr2D. Quite simply we create a random 4x4 image, expand it with the fractal landscape function, blur it, take the values modulo 32 (with the andI function) and use a cycling color palette with 32 entries.

fab mknoise 0 200 4 4 grey.g fab landscape 6 grey.g grey.g fab filter 1 2 1 2 4 2 1 2 1 16 0 grey.g grey.g fab andI 31 grey.g grey.g fab textpalette2rgb pal_Txtr2D.txt grey.g red.g green.g blue.g fab rgb2bmp red.g green.g blue.g Txtr2D.bmp del *.g

I advise you to launch the batch files for other textures in the examples folder. Some modifications have been obtained just by changing the color palette!

The fillwithOs function is very slow, but interesting in my humble opinion. Here we had to increase the size of the fab logo using the edge function, and enlarge the image since fillwithOs requires big monochrome images.

fab bmp2rgb fab_1bpp.bmp shape.g shape.g shape.g fab addborders 10 10 10 10 0 shape.g shape.g fab edge 9 0 255 shape.g shape.g fab scaleup 3 3 shape.g shape.g fab rsbI 255 shape.g logo.g rem Now the logo is set to 0, outside to 255 fab fillwithOs 10 25 5 15 0 0 255 logo.g logo.g fab and shape.g logo.g logo.g fab sampledown 6 6 logo.g logo.g fab rsbI 255 logo.g logo.g fab rgb2bmp logo.g logo.g logo.g TutorialFillWithCircles.bmp del *.g

Now for a more complex example. The picture by BriteLite was created for a contest with the constraint of using 4 colors only. I have always loved the special dithering in it, and wanted to make something similar. The background is similar to Txtr2D but converted to 2 colors with ordered4x4 dithering. The logo is reduced with sampledown, the mask is created with an edge, then both are expanded with scaleup, the logo is converted to 4 colors with ordered2x2 dithering. Last, using the mask, the background and logo are mixed.

Pain by BriteLite remixed with fab

rem background fab mknoise 0 255 4 4 background.g fab landscape 8 background.g background.g fab filter 1 2 1 2 4 2 1 2 1 16 0 background.g background.g fab andI 31 background.g background.g fab ordered4x4 2 background.g background.g rem start shape (expand size to multiples of 8) fab bmp2rgb fab_1bpp.bmp shape.g shape.g shape.g fab addborders 129 129 51 51 0 shape.g shape.g fab sampledown 8 8 shape.g shape.g rem mask for the shape fab edge 2 0 255 shape.g mask.g fab allcolorsbelow 1 mask.g mask.g fab mulI 255 mask.g mask.g fab rsbI 255 mask.g mask.g fab scaleup 2 2 mask.g mask.g rem continue shape (we can put details in it) fab scaleup 2 2 shape.g shape.g fab ordered2x2 4 shape.g shape.g rem mix background, mask and shape fab and mask.g background.g background.g fab or background.g shape.g shape.g fab textpalette2rgb pal_britelite.txt shape.g red.g green.g blue.g fab rgb2bmp red.g green.g blue.g TutorialBriteLite.bmp del *.g

5. Future

The image below show some cool drawing techniques i would like to find an algorithm for (edges for the first two, dithering for the third). All images were made by exocet (aka Herve Piton), a very talented graphician as you can see!