1. Introduction

palutils (palette and image utilities) is a collection of handy tools for processing of image files (mainly 8-bit indexed palette bitmaps). Its main focus is on the usage of image files in small-scale embedded systems.

Currently, the palutils collection consists of the following programs:

bmp2any

translates a BMP file to various formats such as a hex dump or an ANSI C unsigned int array.

memgen

generates a VHDL file of a memory initialized to the BMP image data. The VHDL memory can be mapped to a block RAM (automatically inferred in most modern Xilinx FPGA devices).

genpltenc

generates all 256-color palette encodings that can be represented using only the index encodings relations (of the image data). The number of r (red), g (green) and b (blue) levels of color are associated by the equation: rlev x glev x blev = 256. Acceptable values for the number of levels are: {2, 4, 8, 16, 32, 64}. There exist 21 unique subsets of this form.

genpalette

generates palettes from a predefined set of selections.

palutils

the homonymous program provides several generation, conversion, translation and dumping facilities for 8-bit indexed palette and 256-level greyscale bitmap (BMP) image files.

2. File listing

The palutils distribution includes the following files:

3. Palutils usage

The palutils program can be invoked with several options (see complete options listing below). The usual tasks that can be accomplished with palutils are:

• change a palette to a given BMP file (e.g. for the purpose of pseudocolorization).
• normalize BMP image data to a given or a predefined palette.
• export a BMP file from a VHDL memory dump (a listing of consecutive memory entries encoded either with characters or plain numbers).

palutils can be invoked as:

The complete palutils options listing:

-h

Print this help.

-d

Enable debug output.

-q

Enable quiet run. (unimplemented)

-r

Replace an imported or BMP file palette.

-k

Keep the existing palette of an imported BMP file.

-noplt

Donnot use palette; encode instead an RGB value (R:3-bits,G:3-bits,B:2-bits).

-<char><num>

Convert bitmap data to use a palette. Valid values for char: c (color), g (grey). Valid values for num: {8,256}.

-lev-<chroma> <num>

Indicates that the chromatic components are to be subsampled (when creating the palette) by a power-of-2 factor. All three factors myst be specified, otherwise the defaults {4,8,8} are used. The product of the three factors must yield 256. Valid values of chroma: {r,g,b}. Valid integer factors: {1,2,3,4,5,6}.

-balance

Balance the values of the chromatic components so that min (0x00) and max (0xFF) are always included.

-colorize

Colorize a greyscale image with colors from a specified palette.

-vhdl

Dump generated palette to VHDL ROM.

-inst-<vendor>

Instantiate vendor-specific resources for implementing the palette ROM. Choices: {xilinx}. (unimplemented)

-u <file>

Import VHDL image data dump.

-v<mode>

Read image data dump values as in <mode>. Value options: <mode>={hex (default),int}.

-trad

Accept traditional format of 8/27-color VHDL image data dump.

-x <num>

Read X-dimension size of input image.

-y <num>

Read Y-dimension size of input image.

-s <num>

Factor for scaling the output image.

-i <file>

Import palette data from file.

-o <file>

Export palette data to file.

-b <file>

Read bitmap from file.

-e <file>

Write bitmap to file.

-cmap <file>

Write the colormap (as in NetPBM parlance) to a BMP. The colormap depicts the palette of a 256-color bitmap.

Here follow some simple usage examples of palutils.

1. Generate a 256-level greyscale BMP file from a VHDL memory dump (containing hex values in the range 0-255).

2. Colorization of a greyscale image (monochrome or 256-level) by a given input palette (random assignment of colors). The resulting image is exported as a BMP file as well.

3. Change the palette of a 256-color bitmap file with a user-supplied (or automatically generated) palette. The image data of the bitmap file are altered accordingly.

where for example:

• <char><num> = g256
• <x-dim>     = 320
• <y-dim>     = 200

4. Change the palette of a 256-color bitmap file with a user-supplied (or automatically generated) palette. The image data of the bitmap file are altered accordingly. In addition, generate a VHDL file for palette (with the name: ${imgin}.bmp.vhd).

4. bmp2any usage

The bmp2any utility extracts the image data from a bitmap (BMP) file and dumps them to the specified format. bmp2any can be invoked as follows:

with the following options:

-d

Generate an image data dump for the BMP data.

-x

Generate a hex dump for the BMP data.

-c

Generate a C array for the BMP data (default).

-a

Generate assembly directives for the .data segment.

Usually, bmp2any is used for generating a hex dump of the image data contents of a BMP file. This can be done with the following command:

5. memgen usage

The memgen utility converts a hex dump to an initialized block RAM. It can be used for initializing block RAMs with BMP image data. memgen` is inspired but does not share any code with the ram_image utility of the Plasma (mlite) processor soft-core distribution at the OpenCores website.

memgen can be invoked as follows:

with the following options:

-h

Print this help.

-s <num>

Aggregate size of memory storage.

-l <num>

Program/data word size.

-pmem

Generate memory for program storage.

-dmem

Generate memory for data storage.

-p

Generate VHDL package for monitoring RAM memory signals (one for each memory block).

-m

Generate multiple entities in VHDL dump.

-u

Generate a single block RAM.

-b

Generate VHDL for byte-wide access memory.

-w

Generate VHDL for word-wide access memory.

The following example generates a VHDL package containing the signal declarations and initializations for the data that are stored in the block RAM(s).

6. genpalette usage

The genpalette utility generates palettes from a predefined set of possible selections. The generated palettes are compatible with GIMP and mtPaint.

genpalette can be invoked as follows:

with the following options:

-h

Print this help and exit program.

-g256

Generate a 256-level greyscale palette.

-segm

Generate a customized 256-level color palette for visualizing segmentations.

-bw

Generate a black-and-white palette.

The following examples generates a 256-level greyscale palette.

7. Advanced usage examples

• TODO, please refer to "8. Example scripts" for the time being.

8. Example scripts

The palutils distribution includes a number of bash scripts that make use of the utilities in the package. The usage of these scripts is explained below:

<hex-byte>
...
<hex-byte>

9. Image formats in palutils

The supported image formats in palutils are:

• An image data dump format for describing 8-color (RGB-3) pixels. Each color is represented by a single character. The following table provides the color encodings and their character assignments:

  R	G	B	Char	Description
  0	0	0	N	Black (Noir)
  0	0	1	B	Blue
  0	1	0	G	Green
  0	1	1	C	Cyan
  1	0	0	R	Red
  1	0	1	M	Magenta
  1	1	0	Y	Yellow
  1	1	1	W	White

• An image data dump format for describing 27-color (3-levels: low-, mid-, high per R,G,B) pixels. Each color is represented by a single character. The following table provides the color encodings and their character assignments:

  R	G	B	Char	Description
  00	00	00	N	Black (Noir)
  00	00	01	n	Navy Blue
  00	00	10	B	Blue
  00	01	00	A	Avocado
  00	01	01	s	Teal
  00	01	10	a	Azure
  00	10	00	G	Green
  00	10	01	E	Spring Green
  00	10	10	C	Cyan
  01	00	00	b	Maroon (Brown)
  01	00	01	P	Medium Purple
  01	00	10	I	Indigo
  01	01	00	K	Olive (Khaki)
  01	01	01	g	Gray
  01	01	10	i	Indigo Gray
  01	10	00	L	Chartreuse
  01	10	01	r	Light Green
  01	10	10	c	Light Cyan
  10	00	00	R	Red
  10	00	01	H	Rose (Hot Pink)
  10	00	10	M	Magenta
  10	01	00	O	Orange
  10	01	01	S	Skintone
  10	01	10	m	Light Magenta
  10	10	00	Y	Yellow
  10	10	01	y	Light Yellow
  10	10	10	W	White

• 8-bit paletted color bitmaps

• 8-bit greyscale bitmaps

10. Installation

There exists a quite portable Makefile (Makefile in /src directory). Running make should compile all files: palutils, bmp2any, memgen and genpltenc.

11. Prerequisities

• [mandatory for building] Standard UNIX-based tools
  • gcc (tested with gcc-3.3.3, 3.4.3 and 3.4.4+ on cygwin/x86)
  • make