t4.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * t4.h - definitions for T.4 fax processing
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2003 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: t4.h,v 1.18 2005/11/27 12:36:22 steveu Exp $
00027  */
00028 
00029 /*! \file */
00030 
00031 #if !defined(_T4_H_)
00032 #define _T4_H_
00033 
00034 /*! \page t4_page T.4 image compression and decompression
00035 
00036 \section t4_page_sec_1 What does it do?
00037 The T.4 image compression and decompression routines implement the 1D and 2D
00038 encoding methods defined in ITU specification T.4. They also implement the pure
00039 2D encoding method defined in T.6. These are image compression algorithms used
00040 for FAX transmission.
00041 
00042 \section t4_page_sec_1 How does it work?
00043 */
00044 
00045 #define T4_COMPRESSION_ITU_T4_1D    1
00046 #define T4_COMPRESSION_ITU_T4_2D    2
00047 #define T4_COMPRESSION_ITU_T6       3
00048 
00049 #define T4_X_RESOLUTION_R4          4019
00050 #define T4_X_RESOLUTION_R8          8037
00051 #define T4_X_RESOLUTION_R16         16074
00052 
00053 #define T4_Y_RESOLUTION_STANDARD    3850
00054 #define T4_Y_RESOLUTION_FINE        7700
00055 #define T4_Y_RESOLUTION_SUPERFINE   15400
00056 
00057 /*!
00058     T.4 FAX compression/decompression descriptor. This defines the working state
00059     for a single instance of a T.4 FAX compression or decompression channel.
00060 */
00061 typedef struct
00062 {
00063     int             scan_lines;
00064     int             options;
00065     /*! \brief The type of compression used between the FAX machines. */
00066     int             line_encoding;
00067     int             min_scan_line_bits;
00068     
00069     int             output_compression;
00070     int             output_t4_options;
00071 
00072     char            header_info[50 + 1];
00073     
00074     int             verbose;
00075 
00076     time_t          page_start_time;
00077 
00078     int             bytes_per_row;
00079     int             image_size;
00080     int             image_buffer_size;
00081     uint8_t         *image_buffer;
00082 
00083     TIFF            *tiff_file;
00084     const char      *file;
00085     int             start_page;
00086     int             stop_page;
00087 
00088     int             pages_transferred;
00089     /*! column resolution in pixels per metre */
00090     int             column_resolution;
00091     /*! row resolution in pixels per metre */
00092     int             row_resolution;
00093     int             image_width;
00094     int             row;
00095     int             rows;
00096     int             curr_bad_row_run;
00097     int             longest_bad_row_run;
00098     int             bad_rows;
00099 
00100     uint8_t         *rowbuf;
00101     
00102     int             bit_pos;
00103     int             bit_ptr;
00104     int             bits;
00105     uint32_t        bits_to_date;
00106     
00107     const char      *vendor;
00108     const char      *model;
00109     const char      *local_ident;
00110     const char      *far_ident;
00111     const char      *sub_address;
00112 
00113     /* Decode state */
00114     /*! \brief This variable is set if we are treating the current row as a 2D encoded
00115                one. */
00116     int             row_is_2d;
00117     int             itsblack;
00118     int             row_len;
00119     /*! \brief This variable is used to record the fact we have seen at least one EOL
00120                since we started decoding. We will not try to interpret the received
00121                data as an image until we have seen the first EOL. */
00122     int             first_eol_seen;
00123     /*! \brief This variable is used to count the consecutive EOLS we have seen. If it
00124                reaches six, this is the end of the image. */
00125     int             consecutive_eols;
00126 
00127     uint32_t        *refruns;               /* B&W runs for reference line */
00128     uint32_t        *curruns;               /* B&W runs for current line */
00129 
00130     uint32_t        *pa;
00131     uint32_t        *pb;
00132     int             a0;
00133     int             b1;
00134     /*! \brief The length of the current run of black or white. */
00135     int             run_length;
00136     int             black_white;
00137 
00138     uint32_t        data;
00139     int             bit;
00140 
00141     /*! \brief A point into the image buffer indicating where the last row begins */
00142     int             last_row_starts_at;
00143     /*! \brief A point into the image buffer indicating where the current row begins */
00144     int             row_starts_at;
00145     
00146     /* Encode state */
00147     /*! \brief The reference line for 2D encoding. */
00148     uint8_t         *refrowbuf;
00149     /*! \brief The maximum contiguous rows that will be 2D encoded. */
00150     int             maxk;
00151     /*! \brief Number of rows left that can be 2D encoded, before a 1D
00152                encoded row is used. */
00153     int             k;
00154     /*! \brief The minimum number of encoded bits per row. */
00155     int             min_row_bits;
00156     /*! \brief The current number of bits in the current encoded row. */
00157     int             row_bits;
00158     /*! \brief Error and flow logging control */
00159     logging_state_t logging;
00160 } t4_state_t;
00161 
00162 /*!
00163     T.4 FAX compression/decompression statistics.
00164 */
00165 typedef struct
00166 {
00167     /*! \brief The number of pages transferred so far. */
00168     int pages_transferred;
00169     /*! \brief The number of horizontal pixels in the most recent page. */
00170     int columns;
00171     /*! \brief The number of vertical pixels in the most recent page. */
00172     int rows;
00173     /*! \brief The number of bad pixel rows in the most recent page. */
00174     int bad_rows;
00175     /*! \brief The largest number of bad pixel rows in a block in the most recent page. */
00176     int longest_bad_row_run;
00177     /*! \brief The horizontal resolution of the page in pixels per metre */
00178     int column_resolution;
00179     /*! \brief The vertical resolution of the page in pixels per metre */
00180     int row_resolution;
00181     /*! \brief The type of compression used between the FAX machines */
00182     int encoding;
00183     /*! \brief The size of the image, in bytes */
00184     int image_size;
00185 } t4_stats_t;
00186     
00187 #ifdef __cplusplus
00188 extern "C" {
00189 #endif
00190 
00191 /*! \brief Allocate a T.4 transmit handling context, and
00192            initialise it.
00193     \param file The name of the file to be received.
00194     \param output_encoding The output encoding.
00195     \return The T.4 context, or NULL. */
00196 t4_state_t *t4_rx_create(const char *file, int output_encoding);
00197 
00198 /*! \brief Prepare for reception of a document.
00199     \param s The T.4 context.
00200     \param file The name of the file to be received.
00201     \param output_encoding The output encoding.
00202     \return 0 for success, otherwise -1. */
00203 int t4_rx_init(t4_state_t *s, const char *file, int output_encoding);
00204 
00205 /*! \brief Prepare to receive the next page of the current document.
00206     \param s The T.4 context.
00207     \return zero for success, -1 for failure. */
00208 int t4_rx_start_page(t4_state_t *s);
00209 
00210 /*! \brief Put a bit of the current document page.
00211     \param s The T.4 context.
00212     \param bit The data bit.
00213     \return TRUE when the bit ends the document page, otherwise FALSE. */
00214 int t4_rx_putbit(t4_state_t *s, int bit);
00215 
00216 /*! \brief Complete the reception of a page.
00217     \param s The T.4 receive context.
00218     \return 0 for success, otherwise -1. */
00219 int t4_rx_end_page(t4_state_t *s);
00220 
00221 /*! \brief End reception of a document. Tidy up, close the file and
00222            free the context. This should be used to end T.4 reception
00223            started with t4_rx_create.
00224     \param s The T.4 receive context.
00225     \return 0 for success, otherwise -1. */
00226 int t4_rx_delete(t4_state_t *s);
00227 
00228 /*! \brief End reception of a document. Tidy up and close the file.
00229            This should be used to end T.4 reception started with
00230            t4_rx_init.
00231     \param s The T.4 context.
00232     \return 0 for success, otherwise -1. */
00233 int t4_rx_end(t4_state_t *s);
00234 
00235 /*! \brief Set the encoding for the received data.
00236     \param s The T.4 context.
00237     \param encoding The encoding. */
00238 void t4_rx_set_rx_encoding(t4_state_t *s, int encoding);
00239 
00240 /*! \brief Set the number of pixel columns to expect in a received image.
00241     \param s The T.4 context.
00242     \param columns The number of pixels across the image. */
00243 void t4_rx_set_columns(t4_state_t *s, int columns);
00244 
00245 /*! \brief Set the row resolution to expect for a received image.
00246     \param s The T.4 context.
00247     \param resolution The resolution, in pixels per metre. */
00248 void t4_rx_set_row_resolution(t4_state_t *s, int resolution);
00249 
00250 /*! \brief Set the column resolution to expect for a received image.
00251     \param s The T.4 context.
00252     \param resolution The resolution, in pixels per metre. */
00253 void t4_rx_set_column_resolution(t4_state_t *s, int resolution);
00254 
00255 /*! \brief Set the sub-address of the fax, for inclusion in the file.
00256     \param s The T.4 context.
00257     \param sub_address The sub-address string. */
00258 void t4_rx_set_sub_address(t4_state_t *s, const char *sub_address);
00259 
00260 /*! \brief Set the identity of the remote machine, for inclusion in the file.
00261     \param s The T.4 context.
00262     \param ident The identity string. */
00263 void t4_rx_set_far_ident(t4_state_t *s, const char *ident);
00264 
00265 /*! \brief Set the vendor of the remote machine, for inclusion in the file.
00266     \param s The T.4 context.
00267     \param vendor The vendor string, or NULL. */
00268 void t4_rx_set_vendor(t4_state_t *s, const char *vendor);
00269 
00270 /*! \brief Set the model of the remote machine, for inclusion in the file.
00271     \param s The T.4 context.
00272     \param model The model string, or NULL. */
00273 void t4_rx_set_model(t4_state_t *s, const char *model);
00274 
00275 /*! \brief Allocate a T.4 receive handling context, and
00276            initialise it.
00277     \param s The T.4 context.
00278     \param file The name of the file to be sent.
00279     \return 0 for success, otherwise -1. */
00280 t4_state_t *t4_tx_create(const char *file, int start_page, int stop_page);
00281 
00282 /*! \brief Prepare for transmission of a document.
00283     \param s The T.4 context.
00284     \param file The name of the file to be sent.
00285     \param start_page The first page to send. -1 for no restriction.
00286     \param stop_page The last page to send. -1 for no restriction.
00287     \return The T.4 context, or NULL. */
00288 int t4_tx_init(t4_state_t *s, const char *file, int start_page, int stop_page);
00289 
00290 /*! \brief Prepare to send the next page of the current document.
00291     \param s The T.4 context.
00292     \return zero for success, -1 for failure. */
00293 int t4_tx_start_page(t4_state_t *s);
00294 
00295 /*! \brief Prepare the current page for a resend.
00296     \param s The T.4 context.
00297     \return zero for success, -1 for failure. */
00298 int t4_tx_restart_page(t4_state_t *s);
00299 
00300 /*! \brief Complete the sending of a page.
00301     \param s The T.4 context.
00302     \return zero for success, -1 for failure. */
00303 int t4_tx_end_page(t4_state_t *s);
00304 
00305 /*! \brief Get the next bit of the current document page. The document will
00306            be padded for the current minimum scan line time. If the
00307            file does not contain an RTC (return to control) code at
00308            the end of the page, one will be added.
00309     \param s The T.4 context.
00310     \return The next bit (i.e. 0 or 1). For the last bit of data, bit 1 is
00311             set (i.e. the returned value is 2 or 3). */
00312 int t4_tx_getbit(t4_state_t *s);
00313 
00314 /*! \brief End the transmission of a document. Tidy up, close the file and
00315            free the context. This should be used to end T.4 transmission
00316            started with t4_tx_create.
00317     \param s The T.4 context.
00318     \return 0 for success, otherwise -1. */
00319 int t4_tx_delete(t4_state_t *s);
00320 
00321 /*! \brief End the transmission of a document. Tidy up and close the file.
00322            This should be used to end T.4 transmission started with t4_tx_init.
00323     \param s The T.4 context.
00324     \return 0 for success, otherwise -1. */
00325 int t4_tx_end(t4_state_t *s);
00326 
00327 /*! \brief Set the encoding for the encoded data.
00328     \param s The T.4 context.
00329     \param encoding The encoding. */
00330 void t4_tx_set_tx_encoding(t4_state_t *s, int encoding);
00331 
00332 /*! \brief Set the minimum number of encoded bits per row. This allows the
00333            makes the encoding process to be set to comply with the minimum row
00334            time specified by a remote receiving machine.
00335     \param s The T.4 context.
00336     \param bits The minimum number of bits per row. */
00337 void t4_tx_set_min_row_bits(t4_state_t *s, int bits);
00338 
00339 /*! \brief Set the identity of the local machine, for inclusion in page headers.
00340     \param s The T.4 context.
00341     \param ident The identity string. */
00342 void t4_tx_set_local_ident(t4_state_t *s, const char *ident);
00343 
00344 /*! Set the info field, included in the header line included in each page of an encoded
00345     FAX. This is a string of up to 50 characters. Other information (date, local ident, etc.)
00346     are automatically included in the header. If the header info is set to NULL or a zero
00347     length string, no header lines will be added to the encoded FAX.
00348     \brief Set the header info.
00349     \param s The T.4 context.
00350     \param info A string, of up to 50 bytes, which will form the info field. */
00351 int t4_tx_set_header_info(t4_state_t *s, const char *info);
00352 
00353 /*! \brief Get the header info.
00354     \param s The T.4 context.
00355     \return A string, of up to 50 characters. */
00356 const char *t4_tx_get_header_info(t4_state_t *s);
00357 
00358 /*! \brief Get the row resolution of the current page.
00359     \param s The T.4 context.
00360     \return The resolution, in pixels per metre. */
00361 int t4_tx_get_row_resolution(t4_state_t *s);
00362 
00363 /*! \brief Get the column resolution of the current page.
00364     \param s The T.4 context.
00365     \return The resolution, in pixels per metre. */
00366 int t4_tx_get_column_resolution(t4_state_t *s);
00367 
00368 /*! \brief Get the number of columns in the current page.
00369     \param s The T.4 context.
00370     \return The number of columns. */
00371 int t4_tx_get_columns(t4_state_t *s);
00372 
00373 /*! Get the current image transfer statistics. 
00374     \brief Get the current transfer statistics.
00375     \param s The T.4 context.
00376     \param t A pointer to a statistics structure. */
00377 void t4_get_transfer_statistics(t4_state_t *s, t4_stats_t *t);
00378 
00379 /*! Get the short text name of an encoding format. 
00380     \brief Get the short text name of an encoding format.
00381     \param encoding The encoding type.
00382     \return A pointer to the string. */
00383 const char *t4_encoding_to_str(int encoding);
00384 
00385 #ifdef __cplusplus
00386 }
00387 #endif
00388 
00389 #endif
00390 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1