PicaNew v1.3d
User's Documentation

PicaNew is a tool that performs color quantization and a number of other standard tasks associated with this process.  The name comes from the algorithm it uses to pick the best n colors out of a larger set: PCA -> Principal Component Analysis.  This tool (and large parts of the documentation) is based on Pica, created by Joel Franklin.

Given a set of 24-bit artwork in Microsoft .bmp format, PicaNew will choose up to 255 colors that best represent the true colors found in the bitmaps.  It will then remap the bitmaps, with or without dithering, to this newly created palette and save the resulting data as 8-bit .bmp's in either Microsoft or Phoenix format.

Please note that PicaNew is an advanced tool, intended for use by people who understand concepts such as quantization, rendering and dithering.

Commands
Bring up a DOS prompt box and enter the following to use PicaNew:

picaNew [-v#] @(inputFileName)

where # is the verbosity level, zero is silent, four is maximum verbosity, defaulted to one; and the inputFileName is the name of a file that contains a combination of the commands below.  See the bottom of this document for an example input file.

Please note that this process is very technical in nature, and this document is not intended to explain many advanced concepts such as dithering, subtractive textures, or .mip levels.

quantizeAdditive()	The textures to be quantized will be additive textures.
quantizeAlpha()		The input textures will be 32-bit alpha-channel textures, either in .png or .tga format.
quantizeRGB()		Quantizes the input textures in three dimensions (R, G and B) as opposed to four dimensions (alpha).
quantizeSubtractive()	The quantized textures will be subtractive textures.

NOTE: Only one of the above keywords can be specified per invocation of PicaNew, since they indicate such different procedures.

chooseRange(X,Y)	Instructs PicaNew to choose colors based on the textures in the file list, and put the chosen colors into a palette between indices X and Y (inclusive).
noRender()		PicaNew will not remap any bitmaps following this command.
renderRange(X,Y)	Renders bitmaps in the range of X -> Y of a palette.
basePalName(<palette>)	Instructs PicaNew to read the specified palette in Microsoft .pal format and use it when quantizing or remapping.
outputPath(<path>)	Sets the output path.  This is where all remapped 8-bit art (and the palette, if you instruct PicaNew to save one) will end up.
palOutputName(<palette>) Instructs PicaNew to output a palette to the specified file name, prefixed by the specified path from the outputPath above.
zeroColor(R,G,B)	Sets the zero color (transparent) for a bitmap of a set of bitmaps.  The color specified is ignored in the bitmap color scan and will be mapped to zero in a re-map, regardless of dithering options.
paletteKey(X)		Provides an identifying integer X for a palette, allowing for mixing several palettes with unique keys.
extrudeMipLevels()	Computes mip levels for given textures; dimensions of textures must be powers of two (e.g. 128 x 32).
enableDithering()	Textures will be dithered as they are remapped using standard Floyd-Steinberg processing.
ditherTolerance(X)	If the original 24-bit art is perturbed by an error that diffuses from other pixels when dithering, neighboring pixels will be color-shifted towards the erroneous value, e.g. a while pixel may acquire a bluish hue.  The ditherTolerance command is the maximum allowed displacement in each of the three directions (R, G, B).  This value is most commonly in the 10 to 40 range.
enforcePhoenixSave()	Saves the output bitmaps in Phoenix .bmp format instead of Microsoft .bmp format.  TRIBES uses Phoenix bitmaps, which allows for alpha-channel and other information to be stored. 
maintainEdges() 	Instructs PicaNew not to dither the edges of bitmaps, allowing terrain textures to have matching tile edges.
bitmapListStart()	Signals the beginning of a list of textures (.bmp's and/or .png's) to be processed; wildcards are supported.

Lastly, as more of a convention than a command, any filename listed in the bitmap list can be followed by parentheses and a number.  The number will be how many times PicaNew will "count" this bitmap.  In other words, the colors represented in the entry "biggun.bmp(6)" will each be given six times more "weight" than colors represented by "smallgun.bmp".

Example Input File
Assume that the following is the contents of a file called "remap.pica".

		quantizeRGB()
		outputPath(\8bit)
		palOutputName(\8bit\special.pal)
		enableDithering()
		ditherTolerance(20)
		chooseRange(10,245)
		renderRange(10,245)
		extrudeMipLevels()
		basePalName(windows.pal)
		paletteKey(1)
		bitmapListStart()
		*.bmp

Invoking PicaNew by typing "picanew @remap.pica" at a command prompt will process all files ending in ".bmp" in the current directory, treating them as ordinary RGB textures.  Dithering will be performed with a tolerance of 20, and .mip levels will be computed as well on all bitmaps.  A new palette, called "special.pal", will be created in the directory "\8bit".  This palette will base based on the existing "windows.pal" palette, and will use entries 10 through 245 in rendering the 8-bit textures.  All 8-bit textures produced will be saved in the directory "\8bit".
