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 ------------------------------------------------------------*/