IBS_COMPRESS(3X) — NEWS-OS Programmer’s Manual

NAME

ibs_compress_open, ibs_mhcompress, ibs_mrcompress, ibs_put1d_eol, ibs_put2d_eol, ibs_put_fill, ibs_put1d_rtc, ibs_put2d_rtc, ibs_put_eofb, ibs_comp_flush, ibs_comp_align, ibs_comp_getworksize − functions for compressing bitonal image data

SYNOPSIS

ibs_compress_open(iw, x, w, flag, mode, work, inf, inarg,
outf, outarg, outbuf, outsize)
int iw, x, w, flag;
int mode;
int ∗work;
int (∗inf)();
int inarg;
int (∗outf)();
int outarg;
char ∗outbuf;
int outsize;

ibs_mhcompress(imgadr, work)
char ∗imgadr;
int ∗work;

ibs_mrcompress(imgadr, work)
char ∗imgadr;
int ∗work;

ibs_put1d_eol(work)
int ∗work;

ibs_put2d_eol(next, work)
int next;
int ∗work;

ibs_put_fill(n, work)
int n;
int ∗work;

ibs_put1d_rtc(work)
int ∗work;

ibs_put2d_rtc(work)
int ∗work;

ibs_put_eofb(work)
int ∗work;

ibs_comp_flush(work)
int ∗work;

ibs_comp_align(work)
int ∗work;

ibs_comp_getworksize(w, flag, mode)
int w, flag, mode;

DESCRIPTION

These functions perform compression of G3 or G4 facsimile data.
After first setting the necessary variables using ibs_compress_open, either ibs_mhcompress or ibs_mrcompress is used to compress the data one line at a time.
When compression takes place, the input function inf , which is set using ibs_compress_open , is called, and one line’s worth of image data is read in and compressed. The compressed code data is stored in an output buffer. Whenever the buffer becomes full, the output function outf is used to write the data.

The variables necessary for performing data compression are set using ibs_compress_open.
The size of the area where image data is stored is specified by iw,x and w.
The image width (in dots) is specified using iw. The setting must be a multiple of 16.
The unused portion at the left side of the line is specified in dots as x.
Finally, w is the length (in dots) of image data.
A parameter error results if x + w is greater than iw.
The bit order of the compressed data is specified by flag. If the lower 16 bits of flag are set to 0x0001, the order is MSB (Most Significant Bit) first. If they are set to 0x0000, the order becomes LSB (Least Significant Bit) first. Note that the order for facsimile data is LSB first.
Mode specifies whether or not negative compression is to be allowed. There are some cases, such as dithered images in which ones and zeros frequently alternate horizontally and vertically, where the “compressed” data may actually end up being larger than the original image data. This is referred to as “negative compression.” If mode is set to 0, an error will be returned if negative compression by ibs_mhcompress or ibs_mrcompress is detected. If it is set to 1, any negative compression detected will be ignored. Any other values for mode will result in a parameter error.
work specifies the internal work area whose size must be greater or equal to the return value of function ibs_comp_getworksize.
This work area must not be altered until compression is completely finished.
inf and outf are pointers to I/O functions for the actual data used when performing compression. inf may be set to NULL. This causes the default input functions to be used. In this case, the further knowledge about the input function and internal data format is not required.
inarg and outarg are passed directly to the functions inf and outf, respectively.
outbuf specifies the buffer to be used for the creation of code data. Note that outbuf must be set to an even-numbered address.
outsize is the length of outbuf.

ibs_mhcompress and ibs_mrcompress perform the actual compression of the single line of image data. ibs_mhcompress performs compression using the CCITT T.4, T.6 1-dimensional coding method.
ibs_mrcompress uses either CCITT T.4, T.6 2-dimensional coding or CCITT T.6 basic facsimile coding, whichever is more efficient.
No formats for coding data in uncompressed mode are supported.
Here, first the inf input function is used to read in the image data and generate the array of change-points which constitute internal expressions of the bitonal library. Next, coding takes place and and the code data is stored in the output buffer. Finally, the output function outf when the buffer becomes full or ibs_comp_flush is called.
imgadr indicates the location of the image data. The image data length must be iw /8 bytes. The original image data is not altered by the compression process.
imgadr must be an even-numbered address.

inf is a input function for converting the image data, once it has been read in, into an array of change-points.
If inf is set to NULL, the default input function ibs_encode is called. Here, the input function inf must be used as shown below, and the return value must be negative in case of error.

int (∗inf)(inarg, imgadr, iw, w, x, sline, flag)
int inarg;
char ∗imgadr;
int iw, w, x;
int ∗sline;
int flag;

The values set using ibs_compress_open are passed as inarg, iw, w, x and flag. To imgadr are passed the values set using ibs_mhcompress or ibs_mrcompress. Of these functions, the image data assigned by imgadr must not be altered.
sline is the array of change-points. Its size is ( w + 2 ) ∗ 4.
Refer to ibs_encode or ibs_decode for information on change-points.

outf is a output function for writing the code data.
Here the output function outf must be used as follows to ensure that the returned value is the length of the data to be written. It is necessary that the returned value be negative in case of an error.

int (∗outf)(arg, buf, size)
int arg;
char ∗buf;
int size;

outarg is passed as arg.
outbuf is passed as buf.
The length of the code data in outbuf is passed as size.
At the point this function is called, data of length size bytes is output from buf.

ibs_put1d_eol and ibs_put2d_eol add an EOL (end of scan line sync signal) in the 1-dimensional or 2-dimensional coding scheme.
For the 2-dimensional coding scheme, next of ibs_put2d_eol is set to 1 to specify 1-dimensional compression for the following line or to 2 to specify 2-dimensional compression.

ibs_put_fill add fill bits (variable length string of 0s) in the 1-dimensional or 2-dimensional coding scheme.
Fill bits must be added to ensure that the transmission time of code data, fill bit and EOL is not less than minimum transmission time of the total coded scan line established in the CCITT T.30 pre-message control procedure.
Multiply minimum transmission time by data signaling rate is specified using n.

ibs_put1d_rtc, ibs_put2d_rtc and ibs_put_eofb are used, depending on the compression scheme, at add a RTC (return control) or a EOFB (end of facsimile block) signal at the end of each line.
The code data in the outbuf is all written, even if the buffer is not full.

ibs_comp_flush writes the contents of outbuf without adding anything, even if the buffer is not full.

ibs_comp_align adds 0 fill bits to the code data up to the next byte boundary. Note that the code data is not written.

ibs_comp_getworksize returns the size of the area needed by work. If, for example, images of different sizes are to be processed, the larger value must be used. The value returned is (( w + 2) ∗ 8) + 256
in current version.

ENCODING SCHEMES

A brief overview of the various coding scheme follows. For a more detailed description, refer to CCITT T.4 and CCITT T.6.

1-dimensional coding scheme
This scheme generates codes with the following structure.

EOL (1-dimension)
1-dimension coded data
EOL (1-dimension)
1-dimension coded data
.
.
.
EOL (1-dimension)
1-dimension coded data
RTC (1-dimension)

In fact, after ibs_compress_open is called, ibs_put1d_eol and ibs_mhcompress are called alternately to perform the coding. After the last line has been coded, ibs_put1d_rtc is called to add the RTC code and all the remaining code data in outbuf is written.

There are a number of variations on this scheme. For example, the TIFF Data Compression Scheme 2 is as follows.

1-dimension coded data
1-dimension coded data
.
.
.
1-dimension coded data

In this case, the compressed data for each line must be placed at the byte boundary. This means that after ibs_compress_open is called, ibs_mhcompress and ibs_comp_align are called alternately. After the final line is coded, the data remaining in outbuf is written using ibs_comp_flush.

2-dimensional coding scheme
This scheme includes a parameter called K. After the 1-dimension coded data, a maximum of K − 1 lines are coded in two dimensions. One-dimension coding can take place at a higher frequency than the occurrence of K lines.

If K = 2:

EOL (2-dimension, next = 1)
1-dimension coded data
EOL (2-dimension, next = 2)
2-dimension coded data
EOL (2-dimension, next = 1)
1-dimension coded data
EOL (2-dimension, next = 2)
2-dimension coded data
.
.
.
RTC (2-dimension)

This is basically the same a 1-dimensional coding. Whether next of ibs_put2d_eol should be 1 or 2 is determined by whether the next line is to be coded in one dimension or two.
After that, ibs_mhcompress is called for 1-dimensional coding and ibs_mrcompress for 2-dimensional coding.
After the last line has been coded, ibs_put2d_rtc is called to add the RTC code and all the remaining code data in outbuf is written.

High efficiency 2-dimensional coding
This scheme generates codes with the following structure.

2-dimension coded data
.
.
.
EOFB

After ibs_compress_open is called initially, ibs_mrcompress is called as many times as there are lines to perform the coding. Finally, ibs_put_eofb is called to add the EOFB code and all the remaining code data in outbuf is written.

RETURN VALUES

In case of a parameter error −1 is returned.

If mode is set to 0 for ibs_mhcompress or ibs_mrcompress, −5 is returned if negative compression is detected.
If an error occurs with inf, a −2 is returned, and a −3 is returned if an error occurs with outf.
Also, −4 is returned if the work area is destroyed.

If no errors occur, the number of bytes written is returned.

Always 0 is returned in ibs_comp_align

To determine if any errors were returned by inf or outf, use ibs_getioerror.

FILES

/usr/sony/lib/libibs.a

Museum

Related Articles