|
5
|
1 /*
|
|
|
2 * SpanDSP - a series of DSP components for telephony
|
|
|
3 *
|
|
|
4 * t4.h - definitions for T.4 fax processing
|
|
|
5 *
|
|
|
6 * Written by Steve Underwood <steveu@coppice.org>
|
|
|
7 *
|
|
|
8 * Copyright (C) 2003 Steve Underwood
|
|
|
9 *
|
|
|
10 * All rights reserved.
|
|
|
11 *
|
|
|
12 * This program is free software; you can redistribute it and/or modify
|
|
|
13 * it under the terms of the GNU General Public License version 2, as
|
|
|
14 * published by the Free Software Foundation.
|
|
|
15 *
|
|
|
16 * This program is distributed in the hope that it will be useful,
|
|
|
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
|
19 * GNU General Public License for more details.
|
|
|
20 *
|
|
|
21 * You should have received a copy of the GNU General Public License
|
|
|
22 * along with this program; if not, write to the Free Software
|
|
|
23 * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
|
|
|
24 *
|
|
|
25 * $Id: t4.h,v 1.29 2006/10/24 13:45:28 steveu Exp $
|
|
|
26 */
|
|
|
27
|
|
|
28 /*! \file */
|
|
|
29
|
|
|
30 #if !defined(_T4_H_)
|
|
|
31 #define _T4_H_
|
|
|
32
|
|
|
33 /*! \page t4_page T.4 image compression and decompression
|
|
|
34
|
|
|
35 \section t4_page_sec_1 What does it do?
|
|
|
36 The T.4 image compression and decompression routines implement the 1D and 2D
|
|
|
37 encoding methods defined in ITU specification T.4. They also implement the pure
|
|
|
38 2D encoding method defined in T.6. These are image compression algorithms used
|
|
|
39 for FAX transmission.
|
|
|
40
|
|
|
41 \section t4_page_sec_1 How does it work?
|
|
|
42 */
|
|
|
43
|
|
|
44 #define T4_COMPRESSION_ITU_T4_1D 1
|
|
|
45 #define T4_COMPRESSION_ITU_T4_2D 2
|
|
|
46 #define T4_COMPRESSION_ITU_T6 3
|
|
|
47
|
|
|
48 #define T4_X_RESOLUTION_R4 4019
|
|
|
49 #define T4_X_RESOLUTION_R8 8037
|
|
|
50 #define T4_X_RESOLUTION_R16 16074
|
|
|
51
|
|
|
52 #define T4_Y_RESOLUTION_STANDARD 3850
|
|
|
53 #define T4_Y_RESOLUTION_FINE 7700
|
|
|
54 #define T4_Y_RESOLUTION_SUPERFINE 15400
|
|
|
55
|
|
|
56 /*!
|
|
|
57 T.4 FAX compression/decompression descriptor. This defines the working state
|
|
|
58 for a single instance of a T.4 FAX compression or decompression channel.
|
|
|
59 */
|
|
|
60 typedef struct
|
|
|
61 {
|
|
|
62 /* "Background" information about the FAX, which can be stored in a TIFF file. */
|
|
|
63 /*! \brief The vendor of the machine which produced the TIFF file. */
|
|
|
64 const char *vendor;
|
|
|
65 /*! \brief The model of machine which produced the TIFF file. */
|
|
|
66 const char *model;
|
|
|
67 /*! \brief The local ident string. */
|
|
|
68 const char *local_ident;
|
|
|
69 /*! \brief The remote end's ident string. */
|
|
|
70 const char *far_ident;
|
|
|
71 /*! \brief The FAX sub-address. */
|
|
|
72 const char *sub_address;
|
|
|
73 /*! \brief The text which will be used in FAX page header. No text results
|
|
|
74 in no header line. */
|
|
|
75 const char *header_info;
|
|
|
76
|
|
|
77 /*! \brief The type of compression used between the FAX machines. */
|
|
|
78 int line_encoding;
|
|
|
79 /*! \brief The minimum number of bits per scan row. This is a timing thing
|
|
|
80 for hardware FAX machines. */
|
|
|
81 int min_scan_line_bits;
|
|
|
82
|
|
|
83 int output_compression;
|
|
|
84 int output_t4_options;
|
|
|
85
|
|
|
86 time_t page_start_time;
|
|
|
87
|
|
|
88 int bytes_per_row;
|
|
|
89 int image_size;
|
|
|
90 int image_buffer_size;
|
|
|
91 uint8_t *image_buffer;
|
|
|
92
|
|
|
93 TIFF *tiff_file;
|
|
|
94 const char *file;
|
|
|
95 int start_page;
|
|
|
96 int stop_page;
|
|
|
97
|
|
|
98 int pages_transferred;
|
|
|
99 /*! Column-to-column (X) resolution in pixels per metre. */
|
|
|
100 int x_resolution;
|
|
|
101 /*! Row-to-row (Y) resolution in pixels per metre. */
|
|
|
102 int y_resolution;
|
|
|
103 /*! Width of the current page, in pixels. */
|
|
|
104 int image_width;
|
|
|
105 /*! Current pixel row number. */
|
|
|
106 int row;
|
|
|
107 /*! Total pixel rows in the current page. */
|
|
|
108 int image_length;
|
|
|
109 /*! The current number of consecutive bad rows. */
|
|
|
110 int curr_bad_row_run;
|
|
|
111 /*! The longest run of consecutive bad rows seen in the current page. */
|
|
|
112 int longest_bad_row_run;
|
|
|
113 /*! The total number of bad rows in the current page. */
|
|
|
114 int bad_rows;
|
|
|
115
|
|
|
116 /* Decode state */
|
|
|
117 uint32_t bits_to_date;
|
|
|
118 int bits;
|
|
|
119
|
|
|
120 /*! \brief This variable is set if we are treating the current row as a 2D encoded
|
|
|
121 one. */
|
|
|
122 int row_is_2d;
|
|
|
123 int its_black;
|
|
|
124 int row_len;
|
|
|
125 /*! \brief This variable is used to record the fact we have seen at least one EOL
|
|
|
126 since we started decoding. We will not try to interpret the received
|
|
|
127 data as an image until we have seen the first EOL. */
|
|
|
128 int first_eol_seen;
|
|
|
129 /*! \brief This variable is used to count the consecutive EOLS we have seen. If it
|
|
|
130 reaches six, this is the end of the image. */
|
|
|
131 int consecutive_eols;
|
|
|
132
|
|
|
133 /*! \brief B&W runs for reference line */
|
|
|
134 uint32_t *ref_runs;
|
|
|
135 /*! \brief B&W runs for current line */
|
|
|
136 uint32_t *cur_runs;
|
|
|
137
|
|
|
138 uint32_t *pa;
|
|
|
139 uint32_t *pb;
|
|
|
140 int a0;
|
|
|
141 int b1;
|
|
|
142 /*! \brief The length of the current run of black or white. */
|
|
|
143 int run_length;
|
|
|
144 int black_white;
|
|
|
145
|
|
|
146 uint32_t data;
|
|
|
147 int bit;
|
|
|
148
|
|
|
149 /*! \brief A point into the image buffer indicating where the last row begins */
|
|
|
150 int last_row_starts_at;
|
|
|
151 /*! \brief A point into the image buffer indicating where the current row begins */
|
|
|
152 int row_starts_at;
|
|
|
153
|
|
|
154 /* Encode state */
|
|
|
155
|
|
|
156 /*! Pointer to the buffer for the current pixel row. */
|
|
|
157 uint8_t *row_buf;
|
|
|
158
|
|
|
159 int bit_pos;
|
|
|
160 int bit_ptr;
|
|
|
161
|
|
|
162 /*! \brief The reference pixel row for 2D encoding. */
|
|
|
163 uint8_t *ref_row_buf;
|
|
|
164 /*! \brief The maximum contiguous rows that will be 2D encoded. */
|
|
|
165 int max_rows_to_next_1d_row;
|
|
|
166 /*! \brief Number of rows left that can be 2D encoded, before a 1D encoded row
|
|
|
167 must be used. */
|
|
|
168 int rows_to_next_1d_row;
|
|
|
169 /*! \brief The minimum number of encoded bits per row. */
|
|
|
170 int min_row_bits;
|
|
|
171 /*! \brief The current number of bits in the current encoded row. */
|
|
|
172 int row_bits;
|
|
|
173
|
|
|
174 /*! \brief Error and flow logging control */
|
|
|
175 logging_state_t logging;
|
|
|
176 } t4_state_t;
|
|
|
177
|
|
|
178 /*!
|
|
|
179 T.4 FAX compression/decompression statistics.
|
|
|
180 */
|
|
|
181 typedef struct
|
|
|
182 {
|
|
|
183 /*! \brief The number of pages transferred so far. */
|
|
|
184 int pages_transferred;
|
|
|
185 /*! \brief The number of horizontal pixels in the most recent page. */
|
|
|
186 int width;
|
|
|
187 /*! \brief The number of vertical pixels in the most recent page. */
|
|
|
188 int length;
|
|
|
189 /*! \brief The number of bad pixel rows in the most recent page. */
|
|
|
190 int bad_rows;
|
|
|
191 /*! \brief The largest number of bad pixel rows in a block in the most recent page. */
|
|
|
192 int longest_bad_row_run;
|
|
|
193 /*! \brief The horizontal resolution of the page in pixels per metre */
|
|
|
194 int x_resolution;
|
|
|
195 /*! \brief The vertical resolution of the page in pixels per metre */
|
|
|
196 int y_resolution;
|
|
|
197 /*! \brief The type of compression used between the FAX machines */
|
|
|
198 int encoding;
|
|
|
199 /*! \brief The size of the image, in bytes */
|
|
|
200 int image_size;
|
|
|
201 } t4_stats_t;
|
|
|
202
|
|
|
203 #ifdef __cplusplus
|
|
|
204 extern "C" {
|
|
|
205 #endif
|
|
|
206
|
|
|
207 /*! \brief Allocate a T.4 transmit handling context, and
|
|
|
208 initialise it.
|
|
|
209 \param file The name of the file to be received.
|
|
|
210 \param output_encoding The output encoding.
|
|
|
211 \return The T.4 context, or NULL. */
|
|
|
212 t4_state_t *t4_rx_create(const char *file, int output_encoding);
|
|
|
213
|
|
|
214 /*! \brief Prepare for reception of a document.
|
|
|
215 \param s The T.4 context.
|
|
|
216 \param file The name of the file to be received.
|
|
|
217 \param output_encoding The output encoding.
|
|
|
218 \return 0 for success, otherwise -1. */
|
|
|
219 int t4_rx_init(t4_state_t *s, const char *file, int output_encoding);
|
|
|
220
|
|
|
221 /*! \brief Prepare to receive the next page of the current document.
|
|
|
222 \param s The T.4 context.
|
|
|
223 \return zero for success, -1 for failure. */
|
|
|
224 int t4_rx_start_page(t4_state_t *s);
|
|
|
225
|
|
|
226 /*! \brief Put a bit of the current document page.
|
|
|
227 \param s The T.4 context.
|
|
|
228 \param bit The data bit.
|
|
|
229 \return TRUE when the bit ends the document page, otherwise FALSE. */
|
|
|
230 int t4_rx_put_bit(t4_state_t *s, int bit);
|
|
|
231
|
|
|
232 /*! \brief Complete the reception of a page.
|
|
|
233 \param s The T.4 receive context.
|
|
|
234 \return 0 for success, otherwise -1. */
|
|
|
235 int t4_rx_end_page(t4_state_t *s);
|
|
|
236
|
|
|
237 /*! \brief End reception of a document. Tidy up, close the file and
|
|
|
238 free the context. This should be used to end T.4 reception
|
|
|
239 started with t4_rx_create.
|
|
|
240 \param s The T.4 receive context.
|
|
|
241 \return 0 for success, otherwise -1. */
|
|
|
242 int t4_rx_delete(t4_state_t *s);
|
|
|
243
|
|
|
244 /*! \brief End reception of a document. Tidy up and close the file.
|
|
|
245 This should be used to end T.4 reception started with
|
|
|
246 t4_rx_init.
|
|
|
247 \param s The T.4 context.
|
|
|
248 \return 0 for success, otherwise -1. */
|
|
|
249 int t4_rx_end(t4_state_t *s);
|
|
|
250
|
|
|
251 /*! \brief Set the encoding for the received data.
|
|
|
252 \param s The T.4 context.
|
|
|
253 \param encoding The encoding. */
|
|
|
254 void t4_rx_set_rx_encoding(t4_state_t *s, int encoding);
|
|
|
255
|
|
|
256 /*! \brief Set the expected width of the received image, in pixel columns.
|
|
|
257 \param s The T.4 context.
|
|
|
258 \param columns The number of pixels across the image. */
|
|
|
259 void t4_rx_set_image_width(t4_state_t *s, int width);
|
|
|
260
|
|
|
261 /*! \brief Set the row-to-row (y) resolution to expect for a received image.
|
|
|
262 \param s The T.4 context.
|
|
|
263 \param resolution The resolution, in pixels per metre. */
|
|
|
264 void t4_rx_set_y_resolution(t4_state_t *s, int resolution);
|
|
|
265
|
|
|
266 /*! \brief Set the column-to-column (x) resolution to expect for a received image.
|
|
|
267 \param s The T.4 context.
|
|
|
268 \param resolution The resolution, in pixels per metre. */
|
|
|
269 void t4_rx_set_x_resolution(t4_state_t *s, int resolution);
|
|
|
270
|
|
|
271 /*! \brief Set the sub-address of the fax, for inclusion in the file.
|
|
|
272 \param s The T.4 context.
|
|
|
273 \param sub_address The sub-address string. */
|
|
|
274 void t4_rx_set_sub_address(t4_state_t *s, const char *sub_address);
|
|
|
275
|
|
|
276 /*! \brief Set the identity of the remote machine, for inclusion in the file.
|
|
|
277 \param s The T.4 context.
|
|
|
278 \param ident The identity string. */
|
|
|
279 void t4_rx_set_far_ident(t4_state_t *s, const char *ident);
|
|
|
280
|
|
|
281 /*! \brief Set the vendor of the remote machine, for inclusion in the file.
|
|
|
282 \param s The T.4 context.
|
|
|
283 \param vendor The vendor string, or NULL. */
|
|
|
284 void t4_rx_set_vendor(t4_state_t *s, const char *vendor);
|
|
|
285
|
|
|
286 /*! \brief Set the model of the remote machine, for inclusion in the file.
|
|
|
287 \param s The T.4 context.
|
|
|
288 \param model The model string, or NULL. */
|
|
|
289 void t4_rx_set_model(t4_state_t *s, const char *model);
|
|
|
290
|
|
|
291 /*! \brief Allocate a T.4 receive handling context, and
|
|
|
292 initialise it.
|
|
|
293 \param s The T.4 context.
|
|
|
294 \param file The name of the file to be sent.
|
|
|
295 \return 0 for success, otherwise -1. */
|
|
|
296 t4_state_t *t4_tx_create(const char *file, int start_page, int stop_page);
|
|
|
297
|
|
|
298 /*! \brief Prepare for transmission of a document.
|
|
|
299 \param s The T.4 context.
|
|
|
300 \param file The name of the file to be sent.
|
|
|
301 \param start_page The first page to send. -1 for no restriction.
|
|
|
302 \param stop_page The last page to send. -1 for no restriction.
|
|
|
303 \return The T.4 context, or NULL. */
|
|
|
304 int t4_tx_init(t4_state_t *s, const char *file, int start_page, int stop_page);
|
|
|
305
|
|
|
306 /*! \brief Prepare to send the next page of the current document.
|
|
|
307 \param s The T.4 context.
|
|
|
308 \return zero for success, -1 for failure. */
|
|
|
309 int t4_tx_start_page(t4_state_t *s);
|
|
|
310
|
|
|
311 /*! \brief Prepare the current page for a resend.
|
|
|
312 \param s The T.4 context.
|
|
|
313 \return zero for success, -1 for failure. */
|
|
|
314 int t4_tx_restart_page(t4_state_t *s);
|
|
|
315
|
|
|
316 /*! \brief Check for the existance of the next page. This information can
|
|
|
317 be needed before it is determined that the current page is finished with.
|
|
|
318 \param s The T.4 context.
|
|
|
319 \return zero for next page found, -1 for failure. */
|
|
|
320 int t4_tx_more_pages(t4_state_t *s);
|
|
|
321
|
|
|
322 /*! \brief Complete the sending of a page.
|
|
|
323 \param s The T.4 context.
|
|
|
324 \return zero for success, -1 for failure. */
|
|
|
325 int t4_tx_end_page(t4_state_t *s);
|
|
|
326
|
|
|
327 /*! \brief Get the next bit of the current document page. The document will
|
|
|
328 be padded for the current minimum scan line time. If the
|
|
|
329 file does not contain an RTC (return to control) code at
|
|
|
330 the end of the page, one will be added.
|
|
|
331 \param s The T.4 context.
|
|
|
332 \return The next bit (i.e. 0 or 1). For the last bit of data, bit 1 is
|
|
|
333 set (i.e. the returned value is 2 or 3). */
|
|
|
334 int t4_tx_get_bit(t4_state_t *s);
|
|
|
335
|
|
|
336 /*! \brief Return the next bit of the current document page, without actually
|
|
|
337 moving forward in the buffer. The document will be padded for the
|
|
|
338 current minimum scan line time. If the file does not contain an
|
|
|
339 RTC (return to control) code at the end of the page, one will be
|
|
|
340 added.
|
|
|
341 \param s The T.4 context.
|
|
|
342 \return The next bit (i.e. 0 or 1). For the last bit of data, bit 1 is
|
|
|
343 set (i.e. the returned value is 2 or 3). */
|
|
|
344 int t4_tx_check_bit(t4_state_t *s);
|
|
|
345
|
|
|
346 /*! \brief End the transmission of a document. Tidy up, close the file and
|
|
|
347 free the context. This should be used to end T.4 transmission
|
|
|
348 started with t4_tx_create.
|
|
|
349 \param s The T.4 context.
|
|
|
350 \return 0 for success, otherwise -1. */
|
|
|
351 int t4_tx_delete(t4_state_t *s);
|
|
|
352
|
|
|
353 /*! \brief End the transmission of a document. Tidy up and close the file.
|
|
|
354 This should be used to end T.4 transmission started with t4_tx_init.
|
|
|
355 \param s The T.4 context.
|
|
|
356 \return 0 for success, otherwise -1. */
|
|
|
357 int t4_tx_end(t4_state_t *s);
|
|
|
358
|
|
|
359 /*! \brief Set the encoding for the encoded data.
|
|
|
360 \param s The T.4 context.
|
|
|
361 \param encoding The encoding. */
|
|
|
362 void t4_tx_set_tx_encoding(t4_state_t *s, int encoding);
|
|
|
363
|
|
|
364 /*! \brief Set the minimum number of encoded bits per row. This allows the
|
|
|
365 makes the encoding process to be set to comply with the minimum row
|
|
|
366 time specified by a remote receiving machine.
|
|
|
367 \param s The T.4 context.
|
|
|
368 \param bits The minimum number of bits per row. */
|
|
|
369 void t4_tx_set_min_row_bits(t4_state_t *s, int bits);
|
|
|
370
|
|
|
371 /*! \brief Set the identity of the local machine, for inclusion in page headers.
|
|
|
372 \param s The T.4 context.
|
|
|
373 \param ident The identity string. */
|
|
|
374 void t4_tx_set_local_ident(t4_state_t *s, const char *ident);
|
|
|
375
|
|
|
376 /*! Set the info field, included in the header line included in each page of an encoded
|
|
|
377 FAX. This is a string of up to 50 characters. Other information (date, local ident, etc.)
|
|
|
378 are automatically included in the header. If the header info is set to NULL or a zero
|
|
|
379 length string, no header lines will be added to the encoded FAX.
|
|
|
380 \brief Set the header info.
|
|
|
381 \param s The T.4 context.
|
|
|
382 \param info A string, of up to 50 bytes, which will form the info field. */
|
|
|
383 void t4_tx_set_header_info(t4_state_t *s, const char *info);
|
|
|
384
|
|
|
385 /*! \brief Get the row-to-row (y) resolution of the current page.
|
|
|
386 \param s The T.4 context.
|
|
|
387 \return The resolution, in pixels per metre. */
|
|
|
388 int t4_tx_get_y_resolution(t4_state_t *s);
|
|
|
389
|
|
|
390 /*! \brief Get the column-to-column (x) resolution of the current page.
|
|
|
391 \param s The T.4 context.
|
|
|
392 \return The resolution, in pixels per metre. */
|
|
|
393 int t4_tx_get_x_resolution(t4_state_t *s);
|
|
|
394
|
|
|
395 /*! \brief Get the width of the current page, in pixel columns.
|
|
|
396 \param s The T.4 context.
|
|
|
397 \return The number of columns. */
|
|
|
398 int t4_tx_get_image_width(t4_state_t *s);
|
|
|
399
|
|
|
400 /*! Get the current image transfer statistics.
|
|
|
401 \brief Get the current transfer statistics.
|
|
|
402 \param s The T.4 context.
|
|
|
403 \param t A pointer to a statistics structure. */
|
|
|
404 void t4_get_transfer_statistics(t4_state_t *s, t4_stats_t *t);
|
|
|
405
|
|
|
406 /*! Get the short text name of an encoding format.
|
|
|
407 \brief Get the short text name of an encoding format.
|
|
|
408 \param encoding The encoding type.
|
|
|
409 \return A pointer to the string. */
|
|
|
410 const char *t4_encoding_to_str(int encoding);
|
|
|
411
|
|
|
412 #ifdef __cplusplus
|
|
|
413 }
|
|
|
414 #endif
|
|
|
415
|
|
|
416 #endif
|
|
|
417 /*- End of file ------------------------------------------------------------*/
|
