BMtransform Manual Page

BMtransform - Bitmap conversion and transformation engine.

Synopsis

BMtransform [options] < in_file > out_file

Description

BMtransform will convert various bitmap formats, and can be used to alter the resolution, scale and angle of the image. Additionally, BMtransform can be used to generate barcodes and rastered font strings.

The program will read form standard input and write to standard output, or I/O may be redirected using the "-I" and "-O" options. The image format of the input and output files is nominated by the "-i" and "-o" options. Other options affect how the image is transformed.

Supported File Format

The supported image and output file format options are:

Input
Output
File Format

-iascii ASCII file

-iljet Laserjet print file

-itiff Monochrome TIFF

-ibm -obm Internal bitmap

-idcx -odcx PC fax format

-ifax -ofax Generic UxFax2 fax file

-ig3 -og3 T.4 fax page image

-ipcl -opcl Laserjet raster image

-ipcx -opcx Common PCX exchange format

-og32d Modified read G3 image

-oepson Epson raster image

-otek Tektronix 4207 display format

-ox X windows display

-oxwd X windows XYBitmap

-oz X windows ZPixmap

Transformation Options

-r res Alter the horizontal and/or vertical resolution of an image without altering the scale. The horizontal and vertical resolution may be altered separately.

-vr res

-hr res

The constants std and fine may be used with -r to nominate standard or fine resolution when creating Group 3 fax images.

-rstd is equivalent to -hr200 -vr100

-rfine is equivalent to -hr200 -vr200

-s scale Alter the horizontal and/or vertical scale of an image without altering the resolution. The horizontal and vertical scale may be altered separately. scale is a floating point number greater than 0.0. e.g.

-vs scale

-hs scale

-s0.5 will reduce an image by 50%.

-s2.0 will double the size of an image.

If the scale value is negative, the scale is taken as a maximum image size (either vertical of horizontal) in inches, and the image is scaled to fit within this dimension. This option is used in UxFax2 to fit G3 images onto an A4 page. e.g.

-vs-11.69 -hs-8.26 will fit the image to an A4 page.

-a angle Rotate the image. The angle is nominated in degrees.

Rotation by right angles is faster than rotation by other angles as small as 1 degree.

-a180 will rotate an image 180 degrees.

-R Reverse the image, white becomes black and black becomes white.

-vm Image is mirrored vertically, ie. it is mirrored about a horizontal line which runs through its centre.

-hm Image is mirrored horizontally, ie. it is mirrored about a vertical line which runs through its centre.

Input Options:

The input to BMtransform will be a BM format bitmap file unless nominated otherwise with one of the input options:

-I input_file BMtransform normally copies from standard input, but this option may be used to nominate a source file by name. e.g.;

BMtransform -ifax -opcl min -I 0201 | lp

This example will read an fax image as input from file 0201 instead of standard input.

If input_file contains one or more hash characters (#), they will be substituted by a sequential number for each page image read from input. This option is used with the -ig3 option by UxFax2 when processing received faxes. e.g.

BMtransform -I0201.### -ig3 -ofax -rfine

This example will look for file 0201.001 as the first input file, and 0201.002 etc. for each subsequent page until no matching input file can be found.

-ifax The input file is a CCITT Group 3 encoded image in a format compatible with the UxFax2 fax spooler.

-ig3 The input is a a CCITT Group 3 encoded image.

-iascii The input is a plain ASCII text file, although it may also include PCL4 compatible escape sequences which will be properly interpreted. The default output will be a page image in courier 12 point (10 pitch) font.

-iljet The input is a LaserJet PCL4 print file.

-f filename Argument only applicable when using the -iljet or -iascii options. It names an alternative font table to use instead of the default font table $Utools/Utools/font/font.table.

-ipcl The input will be a PCL raster image. The image may be unencoded, or it may be a TIFF or run-length encoded. Resolution will default to 300 dpi unless it is encoded in the PCL file.

-ipcx The input will one of the common raster formats, either PCX, DCX or TIFF. Only monochrome images are supported by BMtransform. And not all TIFF formats can be guaranteed to work.

-idcx

-itiff

-ibm The input is an X windows bitmap (ASCII) file. This image may be used to manipulate images and icons created using the standard X windows utility bitmap.

-barcode Generate a barcode. This option must be followed by two arguments. The first is the barcode standard which must match one of those named in the configuration file barcode.config. The second is the actual sting to be encoded. The scale (-s) and resolution (-r) are also significant options. e.g.;

BMtransform -barcode EAN13 93/12345/67890 -ox

This example will display a barcode image on an X window terminal. The barcode will be an EAN13 type encoded according the the numbers given.

-text string The input to BMtransform will be a HP LaserJet soft font file. BMtransform will create a image containing the message string composed in the typeface of the soft font. This option may be used to create commonly used font strings as raster images in laser printers without having to have the soft font resident in the printer. e.g.;

zcat $Utools/Utools/font/fax/xpr5ce1a.sfp | \ BMtransform -text "Faxed" -a45 -opcl tiff

This example will produce compressed PCL banner in helvetica typeface at 45 degrees. This banner could be loaded into a laserjet printer to stamp the words "Faxed" across a page.

Output Options

The output of BMtransform will be a BM format bitmap file unless nominated otherwise with one of the following options:

-O output_file BMtransform normally writes to standard output, but this option may be used to nominate a destination file by name. e.g.;

BMtransform -ipcl -odcx -rfine -O Temp$$

This example will write a DCX fax image image to the file Temp$$ instead of standard output. This i necessary when writing DCX images

If output_file contains a hash character (#), the hash will be substituted by a sequential number for each page image to be written. This option is used with the -og3 by UxFax2 when paginating faxes prior to transmission. e.g.;

BMtransform -rfine -ifax -og32d -O 0201.C###

This example produce compressed fax image page files. The first page will be written to file 0201.C001, and ach subsequent page wiil be written to files 0201.C002, 0201.C003 etc.

-opcl The output will be a PCL raster image. It will be unencoded suitable for LaserJet II printers.

-opcl min The output will be a PCL raster image. It will be unencoded suitable for LaserJet II printers, however bitmap data is only produced up to the far righthand black dot. This format will usually reduce the size of a text image file by up to 50%.

-opcl tiff The output will be a PCL raster image. It will be TIFF encoded suitable for LaserJet III printers.

-opcl rle The output will be a PCL raster image. It will be Run-Length encoded suitable for LaserJet III printers.

-obm The output in BMtransform raw (internal) format.

-otek The output will be a Tektronix 4207 TIFF encoded image

-og3 The output will be a CCITT Group 3 encoded image.

-og32d The output will be a 2D Modified Read compressed CCITT Group 3 encoded image.

-ofax The output will be a CCITT Group 3 encoded image in a format compatible with the UxFax2 fax spooler.

-oepson8 Output will be an epson graphics print file (9 pin).

-oepson24 Output will be an epson graphics print file (24 pin).

Both these option also refer to the -vr and -hr options to determine the required print density. Supported print densities are:

V x H (24 pin)
V x H (24 pin)
V x H (9 pin)

72/60 x 60
216/180 x 60
72/60 x 60

72/60 x 80
216/180 x 90
72/60 x 120

72/60 x 90
216/180 x 120
72/60 x 240

72/60 x 120
216/180 x 180

72/60 x 240
216/180 x 360

The vertical resolution is printer dependant, depending upon whether the printer has a true 1:1 aspect ratio, or a 5:6 aspect ratio. Some printers provide an additional escape code to control this.

-opcx The output will one of the popular formats, PCX or DCX. DCX is used by the Windows fax viewer. PCX is a common portable image format.

-odcx

-ox [command] BMtransform will call xwud to display the image in an X window. An option command may be given to be used in place of xwud,.(e.g. "xwud -display titan -reverse"). Clicking on the window will cause the window to close, and any subsequent pages to be displayed.

-oxwd X window XYBitmap dump file

-oz X window ZPixmap dump file

Other Options

-grat Generate a graticule at 10% intervals over the image. This option is used to assist when using the -cut option to cut a particular area from an image.

-clip Remove all white space surrounding the image, so the output image only contains the the full extent of the graphic portion. Generally used with the -iljet to extract graphic images from Windows PCL files. The

-clipv

-cliph

-cut [x1[,y1[,x2[,y2]]]] Cut a rectangular area from the image, where x1 and y1 are the starting coordinates as a percentage of the full area, and x2 and y2 are the finishing coordinates. The defaults for any unsupplied coordinates are x1=0, y1=0, x2=100 and y2=100, which would cut the entire source image.

-nortc "No return to control". Used in conjunction with -og3 or -ofax. The RTC code will not be appended onto the end of the G3 image. This allows multiple G3 images to be concatenated together. This is used primarily in UxFax2 to add a header at the top of a G3 image when sending a page or printing confirmations.

-H "header" Define a header string which will be prepended to each page of the output. The string is an ASCII sequence. Control codes may be encoded using standard "C" and bourne shell syntax, where the carat (^) symbol causes control modification of the following character and a backslash may precede certain characters such as;

\n newline
\r carriage return
\t tab
\b backspace
\f form feed \nnn three digit octal constant

Any other instance of a backslash is substituted with the following character. Therefore;

\\ backslash
\^ carat

-F "footer" Define a footer string which will be appended to each page of the output. The string is an ASCII sequence. Control codes may be encoded using the above syntax. e.g.;

BMtransform -opcl tiff -H "^[&l0E" -F "^[E" | lp

This example will produce an encoded PCL file and send it a laserjet printer. The header code resets the top margin so that the image is placed at the top most extreme of the page, and the footer code will reset the printer and cause it to print the page.

-V1 Verbose mode. Used in conjunction with -O where the filename contains "#" characters. The program will write the name of each generated output filename to standard output.

-D1 Produce de-bug output, output is written to standard error.

Directives

BMtransform will recognise several directives when operating as a PCL interpreter ("-iljet" or "-iascii" options). These directives allow pages to be overlaid with a form, or the inclusion of graphics, or the selection of fonts. The directives are preceded by a dollar symbol and followed by arguments, separated by a full colon (":"). The entire directive may be surrounded by single quote ("'") marks to delimit it from any surrounding text. The syntax is;

[']$Directive:arguments[']

The supported directives are;

FORM:form_name
The form named in the argument will be overlaid on the current page. The form_name is found in the macro table;

$Utools/Utools/macros/macro.table

The macros are stored PCL files, and the location of the file is named in the macro table, although it is usually the same directory that the macro table is also located in.

FONT:font_name
The font named in the argument will be subsequently used for each character plaved on the page. The font_name is an alias and will be found in the font tables, either;

$Utools/Utools/font/font.table

$Utools/Utools/font/font.table.fax

The fonts are PCL bit map soft-fonts, and the location of the font is named in the font table. This will usually be a subdirectory of where the font table is located.

GRAPHICS:filename[,[+|-]x[,[+|-]y]]
The PCL raster image named in the argument will be placed at the current cursor location, unless the option 'x' and 'y' arguments are given, in which case the image will be placed at the absolute position nomintated. The absolute postions are measured in millimetres, and may be given as relative positions by preceding the values with plus or minus symbols.

The file name will be the absolute or relative pathname of a stored PCL raster image. If not path information is given, the file will be located in the sub-directory;

$Utools/Utools/macros/rastered

Input	Output	File Format
`-iascii`		ASCII file
`-iljet`		Laserjet print file
`-itiff`		Monochrome TIFF
`-ibm`	`-obm`	Internal bitmap
`-idcx`	`-odcx`	PC fax format
`-ifax`	`-ofax`	Generic UxFax2 fax file
`-ig3`	`-og3`	T.4 fax page image
`-ipcl`	`-opcl`	Laserjet raster image
`-ipcx`	`-opcx`	Common PCX exchange format
	`-og32d`	Modified read G3 image
	`-oepson`	Epson raster image
	`-otek`	Tektronix 4207 display format
	`-ox`	X windows display
	`-oxwd`	X windows XYBitmap
	`-oz`	X windows ZPixmap

`-r res`	Alter the horizontal and/or vertical resolution of an image without altering the scale. The horizontal and vertical resolution may be altered separately.
`-vr res`
`-hr res`
	The constants std and fine may be used with -r to nominate standard or fine resolution when creating Group 3 fax images.
	`-rstd` is equivalent to `-hr200 -vr100`
	`-rfine` is equivalent to `-hr200 -vr200`
`-s scale`	Alter the horizontal and/or vertical scale of an image without altering the resolution. The horizontal and vertical scale may be altered separately. scale is a floating point number greater than 0.0. e.g.
`-vs scale`
`-hs scale`
	`-s0.5` will reduce an image by 50%.
	`-s2.0` will double the size of an image.
	If the scale value is negative, the scale is taken as a maximum image size (either vertical of horizontal) in inches, and the image is scaled to fit within this dimension. This option is used in UxFax2 to fit G3 images onto an A4 page. e.g.
	`-vs-11.69 -hs-8.26` will fit the image to an A4 page.
`-a angle`	Rotate the image. The angle is nominated in degrees.
	Rotation by right angles is faster than rotation by other angles as small as 1 degree.
	`-a180` will rotate an image 180 degrees.
`-R`	Reverse the image, white becomes black and black becomes white.
`-vm`	Image is mirrored vertically, ie. it is mirrored about a horizontal line which runs through its centre.
`-hm`	Image is mirrored horizontally, ie. it is mirrored about a vertical line which runs through its centre.

`-I input_file`	BMtransform normally copies from standard input, but this option may be used to nominate a source file by name. e.g.;
	`BMtransform -ifax -opcl min -I 0201 \| lp`
	This example will read an fax image as input from file 0201 instead of standard input. If input_file contains one or more hash characters (#), they will be substituted by a sequential number for each page image read from input. This option is used with the -ig3 option by UxFax2 when processing received faxes. e.g.
	`BMtransform -I0201.### -ig3 -ofax -rfine`
	This example will look for file 0201.001 as the first input file, and 0201.002 etc. for each subsequent page until no matching input file can be found.
`-ifax`	The input file is a CCITT Group 3 encoded image in a format compatible with the UxFax2 fax spooler.
`-ig3`	The input is a a CCITT Group 3 encoded image.
`-iascii`	The input is a plain ASCII text file, although it may also include PCL4 compatible escape sequences which will be properly interpreted. The default output will be a page image in courier 12 point (10 pitch) font.
`-iljet`	The input is a LaserJet PCL4 print file.
`-f filename`	Argument only applicable when using the -iljet or -iascii options. It names an alternative font table to use instead of the default font table $Utools/Utools/font/font.table.
`-ipcl`	The input will be a PCL raster image. The image may be unencoded, or it may be a TIFF or run-length encoded. Resolution will default to 300 dpi unless it is encoded in the PCL file.
`-ipcx`	The input will one of the common raster formats, either PCX, DCX or TIFF. Only monochrome images are supported by BMtransform. And not all TIFF formats can be guaranteed to work.
`-idcx`
`-itiff`
`-ibm`	The input is an X windows bitmap (ASCII) file. This image may be used to manipulate images and icons created using the standard X windows utility bitmap.
`-barcode`	Generate a barcode. This option must be followed by two arguments. The first is the barcode standard which must match one of those named in the configuration file barcode.config. The second is the actual sting to be encoded. The scale (-s) and resolution (-r) are also significant options. e.g.;
	`BMtransform -barcode EAN13 93/12345/67890 -ox`
	This example will display a barcode image on an X window terminal. The barcode will be an EAN13 type encoded according the the numbers given.
`-text string`	The input to BMtransform will be a HP LaserJet soft font file. BMtransform will create a image containing the message string composed in the typeface of the soft font. This option may be used to create commonly used font strings as raster images in laser printers without having to have the soft font resident in the printer. e.g.;
	`zcat $Utools/Utools/font/fax/xpr5ce1a.sfp \| \ BMtransform -text "Faxed" -a45 -opcl tiff`
	This example will produce compressed PCL banner in helvetica typeface at 45 degrees. This banner could be loaded into a laserjet printer to stamp the words "Faxed" across a page.

`-grat`	Generate a graticule at 10% intervals over the image. This option is used to assist when using the -cut option to cut a particular area from an image.
`-clip`	Remove all white space surrounding the image, so the output image only contains the the full extent of the graphic portion. Generally used with the -iljet to extract graphic images from Windows PCL files. The
`-clipv`
`-cliph`
`-cut [x1[,y1[,x2[,y2]]]]`	Cut a rectangular area from the image, where x1 and y1 are the starting coordinates as a percentage of the full area, and x2 and y2 are the finishing coordinates. The defaults for any unsupplied coordinates are x1=0, y1=0, x2=100 and y2=100, which would cut the entire source image.
`-nortc`	"No return to control". Used in conjunction with -og3 or -ofax. The RTC code will not be appended onto the end of the G3 image. This allows multiple G3 images to be concatenated together. This is used primarily in UxFax2 to add a header at the top of a G3 image when sending a page or printing confirmations.
`-H "header"`	Define a header string which will be prepended to each page of the output. The string is an ASCII sequence. Control codes may be encoded using standard "C" and bourne shell syntax, where the carat (^) symbol causes control modification of the following character and a backslash may precede certain characters such as;
	\n newline \r carriage return \t tab \b backspace \f form feed \nnn three digit octal constant
	Any other instance of a backslash is substituted with the following character. Therefore;
	\\ backslash \^ carat
`-F "footer"`	Define a footer string which will be appended to each page of the output. The string is an ASCII sequence. Control codes may be encoded using the above syntax. e.g.;
	`BMtransform -opcl tiff -H "^[&l0E" -F "^[E" \| lp`
	This example will produce an encoded PCL file and send it a laserjet printer. The header code resets the top margin so that the image is placed at the top most extreme of the page, and the footer code will reset the printer and cause it to print the page.
`-V1`	Verbose mode. Used in conjunction with -O where the filename contains "#" characters. The program will write the name of each generated output filename to standard output.
`-D1`	Produce de-bug output, output is written to standard error.