about summary refs log tree commit diff
path: root/converter/other/fiasco/doc/fiasco_options_new.3
blob: 884876c7799317c9adc3afce95596fd873fc1b77 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
.\" $Id: fiasco_options_new.3,v 1.2 2000/06/25 16:38:06 hafner Exp $
.TH fiasco 3 "April, 2000" "FIASCO" "Fractal Image And Sequence COdec"

.SH NAME
.B  fiasco_options_new, fiasco_options_set_magnification,
.B fiasco_options_delete, fiasco_options_set_progress_meter,
.B fiasco_options_set_smoothing, fiasco_options_set_tiling, 
.B fiasco_options_set_4_2_0_format, fiasco_options_set_basisfile,
.B fiasco_options_set_chroma_quality, fiasco_options_set_optimizations,
.B fiasco_options_set_prediction, fiasco_options_set_video_param,
.B fiasco_options_set_quantization, fiasco_options_set_frame_pattern
\- define additional options of FIASCO coder and decoder 

.SH SYNOPSIS
.B #include <fiasco.h>
.sp
.BI "fiasco_options_t *"
.fi
.BI "fiasco_options_new"
.fi
.BI "   (void);"
.sp
.BI "void"
.fi
.BI "fiasco_options_delete"
.fi
.BI "   (fiasco_options_t * "options );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_4_2_0_format"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    int "format );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_basisfile"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    const char * "filename );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_chroma_quality"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    float "quality_factor ,
.fi
.BI "    unsigned "dictionary_size );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_frame_pattern"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    const char * "pattern );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_magnification"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    int "level );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_optimizations"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    unsigned "min_block_level ,
.fi
.BI "    unsigned "max_block_level ,
.fi
.BI "    unsigned "max_elements ,
.fi
.BI "    unsigned "dictionary_size ,
.fi
.BI "    unsigned "optimization_level );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_quantization"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    unsigned "mantissa ,
.fi
.BI "    fiasco_rpf_range_e "range ,
.fi
.BI "    unsigned "dc_mantissa ,
.fi
.BI "    fiasco_rpf_range_e "dc_range );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_prediction"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    int "intra_prediction ,
.fi
.BI "    unsigned "min_block_level ,
.fi
.BI "    unsigned "max_block_level );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_progress_meter"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    fiasco_progress_e "type );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_smoothing"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    unsigned "smoothing );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_tiling"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    fiasco_tiling_e "method ,
.fi
.BI "    unsigned "exponent );
.sp
.BI "int"
.fi
.BI "fiasco_options_set_video_param"
.fi
.BI "   (fiasco_options_t * "options ,
.fi
.BI "    unsigned "frames_per_second ,
.fi
.BI "    int "half_pixel_prediction ,
.fi
.BI "    int "cross_B_search ,
.fi
.BI "    int "B_as_past_ref );
.fi

.SH DESCRIPTION
The \fBfiasco_options_new()\fP function allocates and initializes a
FIASCO options object which is used to control additional compression and
decompression parameters.

Conversely, the function \fBfiasco_options_delete()\fP discards the
given FIASCO options object.

Several member functions are available to modify the default behavior
of the FIASCO coder and decoder. 

\fBfiasco_options_set_smoothing()\fP sets the
\fIsmoothing\fP-percentage along partitioning borders when the image
is regenerated; default is 70. This option is used both by the decoder
and encoder. You should use the \fIsmoothing\fP value specified in the
FIASCO file when you are decoding video frames.

\fBfiasco_options_set_magnification()\fP sets the \fImagnification\fP
of the regenerated image; default is 0, i.e., the image geometry is
not changed. This option is used by the decoder only.

\fBfiasco_options_set_4_2_0_format()\fP defines whether the decoder
should use the default 4:4:4 format or the 4:2:0 format. The latter
one significantly reduces the decoding time at the cost of some
additional blocking artefacts. This option is used by the decoder only.

\fBfiasco_options_set_frame_pattern()\fP sets the type of inter frame
compression which should be applied to individual frames of a video
stream; default is "IPPPPPPPPP". 

\fBfiasco_options_set_tiling()\fP sets \fImethod\fP and \fIexponent\fP
of the image tiling algorithm which runs as initial step of the
encoder; by default the image is subdivided into 16 tiles which
are sorted by decreasing variance. 

\fBfiasco_options_set_basisfile()\fP sets the \fIfilename\fP of
the FIASCO initial basis (codebook of dictionary vectors); default is
"small.fco". 

\fBfiasco_options_set_chroma_quality()\fP sets the quality used when
coding the chroma channels of a color image to the term "\fIquality\fP
of luminance / \fIquality_factor\fP"; default is 2. Moreover, the size
of the codebook is limited by \fIdictionary_size\fP; default is 40
elements. 

\fBfiasco_options_set_optimizations()\fP toggles various coding
optimizations. E.g., the size of the dictionary (default is 10000),
the subset of dictionary elements to use for an individual
approximation (default is 5), the size of the image blocks to consider
(4x4, ..., 64x64), and some additional low level
optimizations (default level is 1). 

\fBfiasco_options_set_prediction()\fP enables an additional intra
block prediction by using a DC component approximation. By giving
levels \fImin_block_level\fP and \fImax_block_level\fP the prediction
can be limited to a small range of blocks only. By default, this
method is disabled. 

\fBfiasco_options_set_video_param()\fP defines the framerate (default
is 25) and toggles whether to use half pixel precise motion
compensated prediction (disabled by default), whether to determine
motion vectors of interpolated prediction with the Cross-B-Search
algorithm (disabled by default), and whether to allow B frames to be
used for B frame predicion (disabled by default).

\fBfiasco_options_set_quantization()\fP defines the quantization
parameters of the approximation coefficients. By default the range of
DC coefficients is [-1,+1] using a mantissa of 5 bits (and one sign
bit). By default, all other coefficients are quantized with 3 mantissa
bits in the interval [-1.5,+1.5].

\fBfiasco_options_set_progress_meter()\fP sets the type of progress
meter to be used during coding. By default, an RPM style progress bar
using 50 hash marks (####) is used.

.SH ARGUMENTS
.TP
options
This object encapsulates the various coding and decoding parameters.  

.TP
smoothing
This percentage (range is 0 - i.e., no smoothing - to 100) defines how
much the regenerated image is smoothed along the partitioning borders.

.TP
level
This value gives the magnification of the decoded image with respect
to the original size. Positive values increase and negative values
decrease the width and height of the image by a factor of
2^abs(\fIlevel\fP).

.TP
format
If \fIformat\fP is 0 then the 4:4:4 color image format is used, i.e.,
the chroma channel are of the same size as the luminance. Otherwise,
the 4:2:0 format is used. Then, width and height of each chroma
channel is only one half of the width and height of the luminance.

.TP
method
Defines the algorithm which should be used to sort the image tiles
which are generated in the initial coding step. If \fImethod\fP is
\fBFIASCO_VARIANCE_ASC\fP then the tiles are sorted by variance - the
first tile has the lowest variance. Conversely, when using
\fBFIASCO_VARIANCE_DSC\fP the first tile has the largest variance. If
\fImethod\fP is \fBFIASCO_SPIRAL_ASC\fP then the tiles are sorted like
a spiral starting in the middle of the image. Conversely, when using
\fBFIASCO_SPIRAL_DSC\fP the tiles are sorted like a spiral starting in
the upper left corner.

.TP
exponent
This value sets the number of image tiles - which are generated in the
initial step of the encoder - to 2^\fIexponent\fP.

.TP
pattern
This string defines the sequence of frame types. Character \fIn\fP of
the string defines the type of frame \fIn\fP (\fIpattern\fP is
periodically extended). Three different frame types are available
(case insensitive): choose 'i' for intra-frames (no inter frame
prediction is used), 'p' for predicted frames (a frame of the
past is used for prediction), or 'b' for bi-directional predicted
frames (both a frame of the past and the future is used for
prediction).

.TP
filename
The initial basis (codebook) of the coder is loaded from this
(ASCII) file. Files that already come with FIASCO are "small.fco" (3 elements),
"medium.fco" (132 elements), and "large.fco" (219 elements). 

.TP
quality_factor
When coding chroma channels (Cb and Cr band) the approximation quality
is determined by the term `quality of Y component' / \fIquality_factor\fP.

.TP
dictionary_size
FIASCO uses a dictionary (codebook) of variable size to approximate
individual image blocks. The size of the codebook can be limited by
\fIdictionary_size\fP to reduce the coding time, however, at the cost
of decreasing quality. 

.TP
min_block_level
During coding only those image blocks are considered for approximation
(or prediction) which binary tree level is larger than
\fImin_block_level\fP (minimum value is 3). (Since FIASCO internally
works with binary trees, the size of an image block is determined by
the \fIlevel\fP of the corresponding binary tree). Refer to following
table to convert these values:

.ce
level | width | height
.fi
------+-------+--------
.fi
  0   |    1  |    1  
.fi
  1   |    1  |    2  
.fi
  2   |    2  |    2  
.fi
  3   |    2  |    4  
.fi
  4   |    4  |    4  
.fi
  5   |    4  |    8  
.fi
  6   |    8  |    8  
.fi
  7   |    8  |   16
.fi
------+-------+--------
.fi
The larger this value is the faster the coder runs but the worse the
image quality will be.

.TP
max_block_level
During coding only those image blocks are considered for approximation
(or prediction) which binary tree level is smaller than
\fImax_block_level\fP. The smaller this value is the faster the coder
runs but the worse the image quality will be.

.TP
max_elements
This value defines how many dictionary elements can be
used to approximate an individual image block. The smaller this positive
value (range is 1 to 5) is the faster the coder runs but the worse the
image quality will be. 

.TP
optimization_level
Additional low level optimizations are available by setting
\fIoptimization_level\fP to one of the following values:
.fi
0 standard approximation method
.fi
1 slightly increases the approximation quality, running time is
twice as high as with the standard method 
.fi
2 hardly increases the approximation quality of method 1, running time
is twice as high as with method 1 (this method just remains for
completeness) 
.fi

.TP
intra_prediction
If \fIintra_prediction\fP is set to a non-zero value then an
additional block prediction of intra-frames is enabled. For some
images, the image quality is slightly improved, however, at the cost of
a significantly increased running time of the coder. 

.TP
frames_per_second
This value defines the frame rate, i.e., how many frames per second
should be displayed. This value has no effect during coding, it is just
passed to the FIASCO output file where it is read and used by the
decoder.

.TP
half_pixel_prediction
A non-zero value enables half pixel precise motion compensated
prediction. 

.TP
cross_B_search
A non-zero value enables the fast Cross-B-Search algorithm to determine
the motion vectors of an interpolated prediction. Otherwise,
exhaustive search (in the given search range) is used. 

.TP
B_as_past_ref
A non-zero value allows not only I- and P-frames but also B-frames to be
used for a forward or bi-directional predicion.

.TP
mantissa, range
Approximation coefficients are quantized to a small number of
values (in fixed point format) in the interval [-\fIrange\fP,
+\fIrange\fP]. The number of \fImantissa\fP bits defines the accuracy of
quantization.

.TP
dc_mantissa, dc_range
Approximation coefficients of the DC component are quantized in a
different way: the number of mantissa bits is given by
\fIdc_mantissa\fP whereas the quantization interval is given by
[-\fIdc_range\fP, +\fBdc_range\fP].

.TP
type
This value sets the \fItype\fP of progress meter which should be used
during coding. The following types are available:
.fi
\fBFIASCO_PROGRESS_NONE\fP:  no output at all
.fi
\fBFIASCO_PROGRESS_BAR\fP: print hash marks (###)
\fBFIASCO_PROGRESS_PERCENT\fP: percentage meter (50%)

.SH RETURN VALUES
The function \fBfiasco_decoder_new()\fP returns a pointer to the newly
allocated option object. If an error has been caught, a NULL pointer
is returned.

All set functions return 1 on success and 0 if an error has been
caught.  

In case of an error, use the function fiasco_get_error_message(3) to
get a string with the last error message of FIASCO.

.SH "SEE ALSO"
.br
.BR fiasco_decoder "(3), " fiasco_coder (3)

Ullrich Hafner, Juergen Albert, Stefan Frank, and Michael Unger.
\fBWeighted Finite Automata for Video Compression\fP, IEEE Journal on
Selected Areas In Communications, January 1998
.br
Ullrich Hafner. \fBLow Bit-Rate Image and Video Coding with Weighted
Finite Automata\fP, Ph.D. thesis, Mensch & Buch Verlag, ISBN
3-89820-002-7, October 1999.

.SH AUTHOR
Ullrich Hafner