Encyclopedia of Graphics File Formats Companion

home *** CD-ROM | disk | FTP | other *** search

/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / software / os2 / gbm / readme.txt < prev

Wrap

Text File | 1994-06-01 | 21.6 KB | 476 lines

Generalised Bitmap Module ========================= Supported File Formats ---------------------- Short name : Long name : File extensions Comments Bitmap : OS/2 1.1, 1.2, 2.0 / Windows 3.0 bitmap : .BMP .VGA .BGA .RLE .DIB .RL4 .RL8 Reads any of the above if uncompressed or run-length compressed. Will not read CCITT G3 MH Fax compressed files. Will not read 24 bit RLE files. If input is an OS/2 bitmaparray file then which bitmap can be specified. Input options: index=# (default: 0) Can be made to write OS/2 1.1 or Windows 3.0 / OS/2 2.0 bitmaps Output options: 1.1,win,2.0 (default: 2.0, note win=2.0) The handling of 1bpp bitmaps is a little complicated. When reading 1bpp bitmaps, the palette is ignored. 1's are considered foreground, and they are considered black. 0's are considered background, and they are considered white. This agrees with WorkPlace Shell WPFolder background mode, and most PM programs, but notably disagrees with Windows PBrush. When writing 1bpp bitmaps, the actual 2 colours in the palette are ignored, and a fixed palette is written. This is so that the resulting bitmap will display black on white when displayed by WPFolder etc.. Foreground and background colours in palette can be inverted on input. Input options: inv Foreground and background colours in palette can be inverted on output. Output options: inv Foreground and background colours in bits can be inverted on input. Input options: invb Foreground and background colours in bits can be inverted on output. Output options: invb GIF : CompuServe Graphics Interchange Format : .GIF Reads 1, bit data files. Reads 2, 3 and 4 bit data files and presents them as 4 bit. Reads 5, 6, 7 and 8 bit data files and presents them as 8 bit. Writes 1, 4 and 8 bit data files. Reads "GIF87a" and "GIF89a" style files. Writes "GIF87a" style files. Should correctly handle deferred clear-code in LZW data stream. Will not generate output with deferred clear-code. ie: should not break older GIF readers. Can specify index of image within file on read. Input option: index=# (default 0) Can specify to return decoded data so far rather than error if corrupt. Input option: errok Can specify screen size to write in output screen descriptor. Output options: xscreen=#,yscreen=# (defaults: image size). Can specify background colour index to write in file BMHD header. Output option: background=# (default: 0) Can specify position information in output image descriptor. Output options: xpos=#,ypos=# (defaults: 0,0). Tested on selection of .GIF files from starbase1.austin.ibm.com. Also tested with output of public domain PPMTOGIF.EXE. Compatibility tested with xloadimage and xv. PCX : ZSoft PC Paintbrush Image format : .PCX Reads and writes 1,4,8 and 24 bit colour files. Subset of plane/bits-per-plane combinations supported. Files are read and written using a run-length coding scheme. Tested using Zsoft originated .PCX files. Compressed runs of pixels are not supposed to straddle scan lines. GBM never does this, but some other applications violate this rule. By default, if GBM finds that a run of pixels is longer than the scan line, it will use the leftover pixels on the next scan line. Some images will not load properly, as they require the loading program to discard those pixels in the run that extend beyond the end of the scan line. This behaviour can be enabled in GBM. Input option: trunc TIFF : Microsoft/Aldus Tagged Image File Format support : .TIF Reads and writes 1,4,8 and 24 bit colour files. Can almost read all TIFF 6.0 Baseline compliant files. Can read uncompressed and Packbits images. CCITT Modified huffman compression is the missing peice. Can read some files with extensions to Baseline. Can read 1bpp greyscale and palettised files. Can read Orientation==4 files. Can read PlanarConfiguration==2 files for RGB image data. Can read LZW compressed files too. Can also read CMYK 4 colour seperation files. No JPEG or Y-Cb-Cr support. Writes files that comply with TIFF 6.0 Baseline. Writes uncompressed files only. Data is written out as a single large strip. Can specify image within TIFF file with many images Input option: index=# (default: 0) Can write 1bpp as non-Baseline file preserving fg/bg cols Output option: pal1bpp Can specify informational tags to append on output. Output options: artist=,software=,make=,model=,host=, documentname=,pagename=,imagedescription= Targa : Truevision Targa/Vista bitmap : .TGA .VST .AFI Reads any uncompressed type as 8 bit or 24 bit. Reads both yup and ydown files. Writes out as 8 bit or 16,24,32 bit. Output options: 16,24,32 (default 24) Can be made to write yup and ydown files. Output options: ydown,yup (default: yup) ILBM : Amiga IFF / ILBM Interleaved bitmap format : .IFF .LBM Reads 1 bit palettised files. Reads 2,3 and 4 bit palettised files, returning them as 4 bit. Reads 5,6,7 and 8 bit palettised files, returning them as 8 bit. Reads HAM6, HAM8, SHAM and Extra-Halfbrite images. HAM6, HAM8 and SHAM returned as 24 bit data. Writes 1,4 and 8 bit palettised colour files. Writes 24 bit files by performing simple conversion to HAM6 first. This loses quality but results are still better than 8 bit. Understands the RLE compression scheme used. Uses BMHD, CMAP, CAMG and BODY sections of file only. Only writes BMHD, CMAP, CAMG and BODY sections in output files. Can specify position information in file BHMD header. Output options: xpos=#,ypos=# (defaults: 0,0). Can specify transparent colour to write in file BMHD header. Output option: transcol=# (default: 0) Can specify aspect ratio to write in file BMHD header. Output options: xaspect=#,yaspect=# (defaults: 1,1). Can specify screen size to write in output BMHD header. Output options: xscreen=#,yscreen=# (defaults: image size). Note that when DeluxePaint etc. try to load an 8 bit IFF file, they switch to a 32 colour (5 bit mode) and only read the 5 least significant planes of the file - this generally looks yukky! Tested using DeluxePaint sample bitmaps. YUV12C : YUV12C M-Motion Frame Buffer : .VID Reads files and presents data as 24 bit data. Writes 24 bit data files by converting them into 12 bit YUV. VID files MUST be a multiple of 4 pixels wide. When writing a non-multiple of 4, the last 1, 2 or 3 pixels are lost. Can specify image origin information in YUV12C header. Output options: xpos=#,ypos=# (defaults: 0,0). Tested using M-Control Program 2.0, Browser sample application. Greymap : Portable Greyscale-map (binary P5 type) : .PGM Credit for file format to Jef Poskancer. No palette present in file format. Reads 8 bit grey scale files. Writes red, green, blue plane or greyscale equivelent of 8 bit image. Output options: r,g,b,k (default: k) Pixmap : Portable Pixel-map (binary P6 type) : .PPM Credit for file format to Jef Poskancer. Reads and writes 24 bit unpalettised RGB data files. KIPS : IBM KIPS : .KPS Reads 8 bit palettised files. Will look for palette in .PAL file unless .KPL file specified. Input options: pal,kpl (default: pal) Writes 8 bit palettised files. Will write palette in .PAL file unless .KPL file specified. Output options: pal,kpl (default: pal) IAX : IBM Image Access eXecutive : .IAX Reads array as 8 bit greyscale. File format does not hold image dimensions. Hence code assumes width is 512 pixels unless overridden. Input options: width=# (default: 512) File format does not include palette. Writes red, green, blue plane or greyscale equivelent of 8 bit image. Output options: r,g,b,k (default: k) XBitmap : X Windows bitmap : .XBM Reads 1bpp X bitmaps, presenting 1's as black, 0's as white. Writes 1bpp X bitmaps, darkest colours as 1's, brightest colour as 0's. Tested upon some .XBM files obtained from spock.hursley.ibm.com Sprite : Archimedes Sprite format from RiscOS : .SPR Technically sprite files have no extension, but GBM recognises .SPR. Reads 1,4 and 8 bit sprites. 'First bit' value in header must be a multiple of 8 (v.likely). Will only read image plane, will ignore any mask plane. Will handle case when no palette present in file. Will default to the default Wimp palette in this case. If input contains more than one sprite then which can be specified. Input options: index=# (default: 0) Will output 1,4 and 8 bit files. Will write a palette in the file. Will only write an image plane, ie: no mask plane. Will write a 16 entry palette for 8 bit data (not 64 entry). Will map to wierd archmedes palette when writing 8 bit data. Tested reading 4bpp sprites with no palette. Tested reading 8bpp sprites with no palette and with 64 entry palette. Sprites generated by GBM have been loaded on RiscOS. Remember: Use SetType to change type of file from PC-file to Sprite, by SetType option of filer menu or "*SetType <filename> Sprite". Sample Applications ------------------- GBMHDR - Display header information from bitmap files usage: gbmhdr [-g] [-s] {fn.ext{,opt}} -g don't guess bitmap format, try each type -s be silent about errors fn.ext{,opt} input filenames (with any format specific options) Bitmap when ext in [BMP VGA BGA RLE DIB RL4 RL8] GIF when ext in [GIF] PCX when ext in [PCX] TIFF when ext in [TIF] Targa when ext in [TGA VST AFI] ILBM when ext in [IFF LBM] YUV12C when ext in [VID] Greymap when ext in [PGM] Pixmap when ext in [PPM] KIPS when ext in [KPS] IAX when ext in [IAX] XBitmap when ext in [XBM] Sprite when ext in [SPR] opt bitmap format specific option to pass to bitmap reader Note that the GBM module only ever surfaces the size and bits per pixel of images (regardless of the other information present in the header). All GBM programs have access to the bitmap file formats documented above, although this list is omitted in subsequent documentation. GBMREF - Reflect in horizontal and/or vertical directions usage: gbmref [-h] [-v] [-t] fn1.ext{,opt} [fn2.ext{,opt}] flags: -h reflect horizontally -v reflect vertically -t transpose x for y fn1.ext{,opt} input filename (with any format specific options) fn2.ext{,opt} optional output filename (or will use fn1 if not present) bitmap formats and options as before Certain non-obvious combinations of -h, -v and -t can be very usefull. None of them can be used for just file format translation. -h -v reflect both, equivelent to 180 degree turn -h -t equivelent to 90 degree turn clockwise -v -t equivelent to 90 degree turn anti-clockwise. GBMSUB - Extract a subrectangle of a bitmap usage: gbmsub [-x x] [-y y] [-w w] [-h h] fn1.ext{,opt} [fn2.ext{,opt}] flags: -x x left edge of rectangle (default 0) -y y bottom edge of rectangle (default 0) -w w width of rectangle (default width of image - x) -h h height of rectangle (default height of image - y) fn1.ext{,opt} input filename (with any format specific options) fn2.ext{,opt} optional output filename (or will use fn1 if not present) bitmap formats and options as before If none of the -x,-y,-w and -h options are supplied the defaults cover the whole of the input file. Hence this program will just read one file and write the data as another. Great for format conversion. GBMBPP - Do various bits per pixel conversions usage: gbmbpp [-m map] [-e] [-h] fn1.ext{,opt} [fn2.ext{,opt}] flags: -m map mapping to perform (default 7x8x4) bw black and white vga 16 colour VGA 8 8 colour (in 4 bit file) 4g 4 bit greyscale 7x8x4 7 levels red, 8 green, 4 blue 8514/A 6x6x6 6 levels red, 6 green, 6 blue 8g 8 bit greyscale tripel 64 reds, 64 greens, 64 blues tripel freqR:G:B:N keep R red, G green, b blue bits, and map to N most used colours in 8 bit palette R:G:B keep R red, G green, B blue bits (eg: 8:8:8) -e enable error-diffusion (default is to truncate) -e not with -m 8g or tripel or freq or -h -h enable halftoning (default is to truncate) -h only with -m 7x8x4, 6x6x6, 8, vga or R:G:B, with no -e fn1.ext{,opt} input filename (with any format specific options) fn2.ext{,opt} optional output filename (or will use fn1 if not present) bitmap formats and options as before This program reads the input bitmap. If it is not 24 bit, then it is expanded to 24 bit per pixel. The data is then processed using the supplied mapping giving a 24,8,4 or 1 bit per pixel image, which is then written to the output bitmap file. The bw mapping produces a 1 bpp output file, vga and 4g gives 4 bit output files, 7x8x4, 6x6x6, 8g, freq and tripel give 8 bit output files. R:G:B (where R,G and B are numbers in the range 0 to 8), gives a 24 bit output file where only the top R bits of red are non-zero, the top G of green and B of blue. The normal way to map is simply to map each colour in the source bitmap to the closest one in the destination bitmap. However if -e is supplied, error diffusion is used to get a smoother result. Also, if -h is supplied halftoning may be used instead. -e and -h are not valid together, and are only valid with certain mappings. GBMGAMMA - Convert between various colour spaces usage: gbmgamma [-m map] [-g gamma] [-s shelf] fn1.ext{,opt} [fn2.ext{,opt}] flags: -m map mapping in the form ?_to_? (default: i_to_l), where ? is i physical intensitys (eg: raytracer output) p gamma corrected for a specific monitor l L* cyclometric linear perceived intensitys (as in PM) -g gamma set monitor gamma (default 2.1) -s shelf set monitor shelf (default 0.0) gamma and shelf only used for mapping to or from p for 8514 monitor gamma=2.3,shelf=0.136 for 8515 monitor gamma=2.1,shelf=0.0 fn1.ext{,opt} input filename (with any format specific options) fn2.ext{,opt} optional output filename (or will use fn1 if not present) bitmap formats and options as before This program reads a bitmap and assumes the pixel values in it are in the input colour space. If the bitmap has a palette it maps each palette entry according to the supplied mapping, otherwise it maps each individual 24 bit pixel. For example, if you get a 24 bit per pixel image from a Windows video capture program, the odds are in may be in a gamma corrected colour space with a gamma of 2.2. You can convert this to the L* cyclometric colour space used by PM by typing "gbmgamma -m p_to_l -g 2.2 captured.bmp nicepm.bmp". The shelf option is primarily for when converting to a gamma corrected colour space for a specific monitor (when you aren't going to use PM to display the bitmap, and the display program doesn't do any correction). Some monitors don't actually start to light up pixels until the pixel values are a certain value. The example of 0.136 for the 8514 monitor says that pixel values 0 to 0.136*255=35 all come out equally black! Normally "-s shelf" will not be used. To be done ---------- gbmexp [-X X] [-Y Y] [-x x] [-y y] fn1.ext{,opt} [fn2.ext{,opt}] Colour spaces ------------- If a light is physically twice as bright, the eye does not necessarily see it as twice as bright. Also, if a pixel is written onto a monitor screen with twice the value, the physical intensity of the pixel is not necessarily double. How exactly should numbers inside a bitmap file relate to physical or perceived intensitys when displayed on the screen? In OS/2 PM perceived intensitys are proportional to the values in the bitmap file. Pixels in such a bitmap are in the 'L* cyclometric' colour space. Ray Tracers often write pixel values in the bitmap proportional to the physical intensity computed for that ray. Such data is in the 'intensity' colour space. Finally, if a bitmap holds values computed in such a way as to compensate for the gamma of the monitor (ie: intensitys transformed to cancel out the gamma of the monitor), then the data is in a 'gamma corrected' colour space. So, if you have some Ray Tracer output, and you wish to display on an 8514 monitor WITHOUT using OS/2 PM, then to get a decent colour rendition, you must map the bitmap from the 'intensity' to a 'gamma corrected' colour space. To do this you must know the gamma of the 8514 monitor (which is about 2.1). Also, if you have some Ray Tracer output, and you wish to display on OS/2 PM, then to get a decent rendition you must map the bitmap from the 'intensity' to the 'L* cyclometric' colour space. GBMGAMMA is a colour mapping program capable of performing mappings between any 2 of the 3 colour spaces above. Mapping of this sort should really be done on 24 bit data, before error-diffusion or halftoning takes place. Some examples ------------- gbmhdr *.bmp *.tif Displays the headers of all the bitmaps and TIFF files gbmref file.bmp file.tga Perform no reflection (no -h, -v or -t). Hence simply converts file from Bitmap to Targa format! gbmref -h larrow.tga rarrow.tga Reflects larrow.tga to make rarrow.tga gbmref -h -t profit.gif loss.gif The combination of a horizontal flip with a transpose gives a 90 degree rotation clockwise. Thus a graph going up from bottom left to top right, ends up going from top left to bottom right! gbmref -v uarrow.pcx "darrow.lbm,xaspect=5,yaspect=6,xscreen=320,yscreen=200" Reflects uarrow.pcx to make darrow.lbm Output options defined for ILBM files used to write to aspect ratio and screen size fields in output .lbm file. Note: some command processors (such as OS/2 CMD.EXE) will split command line arguments at spaces and commas, so we quote second argument. gbmsub -x 100 -y 50 page.bmp Trims 100 pixels off the left, and 50 off of the bottom Note: no second filename given, so output overwrites page.bmp gbmbpp -m 7x8x4 24bit.tga 8bit.bpp Maps a 24 RGB image to the 8514/A PM palette Note: Source image format (Targa) not same as output format (Bitmap) gbmbpp -m 7x8x4 -h 24bit.bmp nice8bit.bmp As above but with halftoning gbmbpp -m 7x8x4 -e 24bit.bmp nice8bit.bmp As above, but with error diffusion gbmbpp -m vga -e 24bit.bmp nice4bit.bmp As above, but suitable for VGA display gbmbpp -m 5:5:5 -e 8r8g8b.tga "5r5g5b.tga,16" Error diffuse from 24 bit RGB to 15 bit RGB (bottom 3 bits of each of R,G and B become zero) Output option ",16" ensures data written in Targa-16 form This reduces wasted disk space. gbmbpp -m freq8:8:8:240 24bit.bmp 8bit.bmp Finds 240 most frequently used colours. For other colours finds closest match in most common 240 colours. Maps colours in 24bit.bmp to give 8 bit output file. If excessively large number of colours in original, may truncate bits. gbmgamma -m i_to_l raytrace.bmp pmsuited.bmp raytrace.bmp has pixels values proportional to physical intensity pmsuited.bmp is made with pixels proportional to perceived intensity Source code ----------- The main part of GBM is highly portable 32 bit C, and has been compiled on OS/2 2.x, AIX 3.2 and other systems. Certain associated parts, notably the GBMV and GBMV2 OS/2+PM programs are OS/2 dependant. Full source to these should be available where you obtained this package. Public domain declaration ------------------------- I wrote all this code in my own time on my own equiptment. I used public non-confidential information to do so. I hereby place all this code into the public domain. Feel free to do whatever you like with it. No copyright / no royalties / no guarantees / no problem. Caveat Emptor! Change Log ---------- 11/5/92 Initial general release. Various dates Fixed assorted bugs in various parts of GBM. Dropped support for 16 bit systems. Changed all code to now be compiled multithreaded. Changed GBM library to a DLL under OS/2, saved at least 500Kb. /NOI now required when linking with GBM.LIB. Added textual error messages. Accelerated halftoning and error-diffusion. Added GIF, X Bitmap and RiscOS Sprite support. Extensively improved TIFF file support (now almost Baseline). Extensively improved IFF support (HAM6, HAM8 etc.). GBM structure enlarged => PLEASE RECOMPILE Addition of bitmap transpose (and hence rotate) capability. Added GBMV2, the flagship OS/2+PM program to show off GBM. 28/9/93 Handling of 1bpp data has changed - now honors colours. Windows / (OS/2 2.0 subset) not OS/2 1.1 bitmaps now default. Improved error checking some file readers. Addition of -s and -g options to GBMHDR. Copy supplied to IBM OS/2 Developer Connection. 11/11/93 Added F3 to close GBMV and GBMV2. Fixed keyboard scrolling in GBMV2. Added general (single level) Undo capability to GBMV2. Added GBMWPOBJ.CMD to set up Workplace Shell Objects.