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 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639
|
.\"
.TH "y4mscaler" "1" "February 14, 2003" "y4mtools" "y4mtools manual"
.hw y4mscaler
.SH "NAME"
y4mscaler \- Scale/crop/translate a YUV4MPEG2 stream
.SH "SYNOPSIS"
.B y4mscaler
.RI [ options ]
.I < Y4Mstream > Y4Mstream
.SH "DESCRIPTION"
\fBy4mscaler\fP is a general-purpose video scaler which operates on
YUV4MPEG2 streams, as produced and consumed by the MJPEGtools such
as \fBlav2yuv\fP and \fBmpeg2enc\fP(1).
\fBy4mscaler\fP is meant to be used in a pipeline. Thus, input is from stdin,
and output is to stdout.
The essential function of \fBy4mscaler\fP is to scale a specified "active"
region of
the input stream (the source) into a specified active region of the output
stream (the target). Pixels outside of the active region of the source are
ignored; pixels outside of the active region of the target are filled with
a background color. The source may additionally have a matte applied to it;
pixels outside the source matte are set to a separately specified background
color.
\fBy4mscaler\fP correctly handles chroma subsampling, and thus it
can also perform chroma subsampling conversions.
The YUV4MPEG2 stream format supports three varieties of 4:2:0 subsampling,
as well as 4:1:1, 4:2:2, 4:4:4, a 4:4:4 modes with an alpha channel,
and a monochrome luma-only mode.
(See "NOTES ON CHROMA MODES AND SUBSAMPLING".)
\fBy4mscaler\fP can perform simple interlacing conversions: switching from
top-field-first to bottom-field-first and vice-versa (by lossily discarding
the first field), and creating a progressive stream from interlaced
by discarding every other field (effectively halving the vertical resolution).
The source and target are defined by many, many parameters, but \fBy4mscaler\fP
has many, many heuristics built-in to automagically set them appropriately.
Most source parameters are taken from the input stream header. Remaining
source and target parameters which are not specified by the user are guessed
in a sane manner.
\fBy4mscaler\fP includes preset parameters for a number of common target
streams:
DVD, VideoCD (VCD), SuperVCD (SVCD), associated still image formats, and DV.
.SH "EXAMPLES"
To create a stream appropriate for use in an SVCD:
.RS 5
y4mscaler -O preset=svcd
.RE
To create a stream for a VideoCD (a non-interlaced format), from a DV source
(an interlaced format), shifting the input frame 4 pixels to the left:
.RS 5
y4mscaler -I ilace=bottom-only -I active=-4+0cc -O preset=vcd
.RE
To take a widescreen NTSC DV source, and convert it to a letterboxed stream,
with blue bars on the top and bottom:
.RS 5
y4mscaler -O sar=ntsc -O bg=RGB:0,0,255
.RE
To take a widescreen NTSC DV source, and convert it to a "fullscreen" stream
(i.e. the sides are clipped, just like on TV):
.RS 5
y4mscaler -O sar=ntsc -O infer=clip
.RE
To take a centered, letterboxed NTSC source, and convert it to a widescreen
(16:9) format stream for DVD, with the black bars removed:
.RS 5
y4mscaler -O preset=dvd -O sar=ntsc_wide -O infer=clip
.RE
To take the center 100x100 pixel chunk of an NTSC DV stream, surround it with
a 20-pixel blue border, and blow that up to a full-screen SuperVCD stream:
.RS 5
y4mscaler -I active=140x140+0+0cc -I matte=100x100+0+0cc -I bg=RGB:0,0,255 -O preset=svcd
.RE
.SH "OPTIONS"
The first three options, -v, -V, and -h, are simple straightforward options
which take either no arguments or one numeric argument.
.TP 5
.BI \-v " [0,1,2]"
Set verbosity level.
0 = warnings and errors only.
1 = add informative messages, too (default).
2 = add chatty debugging message, too.
.TP 5
.BI \-V
Show version information and exit.
.TP 5
.BI \-h
Show a help message (synopsis of options).
.P
The -I, -O, and -S options each take one argument of the form
.I parameter=value,
which specify parameters for the input, output, and scaling, respectively.
These options can be used repeatedly to specify multiple parameters.
The parameter names and values are not case-sensitive.
Definitions of the form "parameter=[AAA|BBB|CCC]" mean that only one of
the listed keywords AAA, BBB, or CCC may be chosen.
Succeeding options will override earlier ones.
.TP 5
.BI \-I " input_parameter"
.RS
Specify parameters for the source/input stream. All '-I' arguments are
evaluated in order, and later arguments on the command-line will override
earlier ones. All '-I' arguments are evaluated before any '-O' arguments.
.TP 3
.BI active= WxH+X+Yaa
Specify the active region of the source frame, which is scaled to fit the
active region of the target frame. The default is the full frame.
(The "WxH" may be omitted, and the region size defaults to the size of
of the source frame.)
W and H are width and height.
X and Y are the offset of the anchor point.
"aa" is the anchor mode (default: TL); see "NOTES ON REGION GEOMETRY" for details.
.br
Example: active=200x180+30+24cc
.TP 3
.BI matte= WxH+X+Y
Specify a matte region for the source frame. All pixels outside of this region
are set to the source background color. The default matte is the full frame.
(The "WxH" may be omitted, and the region size defaults to the size of
of the source frame.)
W and H are width and height.
X and Y are the offset of the anchor point.
"aa" is the anchor mode (default: TL); see "NOTES ON REGION GEOMETRY" for details.
.br
Example: matte=200x180+30+24cc
.PP
.BI bg= RGB:r,g,b
.br
.BI bg= YCBCR:y,cb,cr
.br
.BI bg= RGBA:r,g,b,a
.br
.BI bg= YCBCRA:y,cb,cr,a
.RS 3
Set the source background color. Pixels outside of the source's matte
region are set to this color. One can specify the color as either
a R'G'B' or Y'CbCr triplet. For example, the default color is black,
specified as "bg=YCBCR:16,128,128" or "bg=RGB:0,0,0".
The 'A' versions will set the alpha (transparency) value of the color.
The alpha range is [0,255] for RGBA and [16,235] for YCBCRA.
The default is fully-opaque (255 for RGBA, 235 for YCBCRA).
.RE
.TP 3
.BR norm= [ NTSC | PAL | SECAM ]
Specify the "norm" of the source stream. This is normally inferred from
the stream header.
.TP 3
.BR ilace= [ NONE | TOP_FIRST | BOTTOM_FIRST | TOP_ONLY | BOTTOM_ONLY ]
Specify the interlacing used by the source stream. NONE, TOP_FIRST, and
BOTTOM_FIRST correspond to non-interlaced, top-field-first, and
bottom-field-first. These values are normally inferred from the stream
header; specifying them will override the stream header.
.br
TOP_ONLY and BOTTOM_ONLY specify that only the top or bottom field of each
frame should be used; the other field is discarded. These options can only
be used with an interlaced input, and cause the interlaced stream to be
treated as a progressive stream with half the height. (This is particularly
useful in creating a VCD from a full-size interlaced input stream.)
These two special options can only be used when the source is a pure
progressive stream (as opposed to a YUV4MPEG2 "mixed-mode" stream).
.TP 3
.BR chromass= [ 420JPEG | 420MPEG2 | 420PALDV | 444 | 422 | 411 | mono | 444alpha ]
Specify the chroma subsampling mode used in the source stream.
This parameter is inferred from the stream header, so this keyword should
almost never be used in a source specification.
The only useful reason to specify this keyword is to override one variety
of 4:2:0 with another. Any other use will cause processing to fail.
.PP
.BI sar= N:D
.br
.BR sar= [ NTSC | PAL | NTSC_WIDE | PAL_WIDE ]
.RS 3
Specify the sample-aspect-ratio of the source stream. The value can either
be or numeric ratio (such as "10:11") or one of the keywords, which
correspond to the CCIR-601 values for 4:3 or 16:9 displays, respectively.
This parameter is usually inferred from the stream header.
.RE
.RE
.TP 5
.BI \-O " output_parameter"
.RS
Specify parameters for the destination/output stream. All '-O' arguments are
evaluated in order, and later arguments on the command-line will override
earlier ones. All '-O' arguments are evaluated after any '-I' arguments.
.PP
.BI size= WxH
.br
.B size=SRC
.RS 3
Set the output/target frame size, as width W and height H in pixels.
Use the keyword \fBSRC\fP to specify that the target frame size should match
the source frame size.
.RE
.TP 3
.BI active= WxH+X+Yaa
Specify the active region of the target frame, into which the active region
of the source frame is scaled.
The default is the full target frame.
(The "WxH" may be omitted, and the region size defaults to the size of
of the target frame.)
W and H are width and height.
X and Y are the offset of the anchor point.
"aa" is the anchor mode (default: TL); see "NOTES ON REGION GEOMETRY"
for details.
.br
Example: active=200x180+30+24cc
.PP
.BI bg= RGB:r,g,b
.br
.BI bg= YCBCR:y,cb,cr
.br
.BI bg= RGBA:r,g,b,a
.br
.BI bg= YCBCRA:y,cb,cr,a
.RS 3
Set the target background color. Pixels outside of the target's active
region are set to this color. One can specify the color as either
a R'G'B' or Y'CbCr triplet. For example, the default color is black,
specified as "bg=YCBCR:16,128,128" or "bg=RGB:0,0,0".
The 'A' versions will set the alpha (transparency) value of the color.
The alpha range is [0,255] for RGBA and [16,235] for YCBCRA.
The default is fully-opaque (255 for RGBA, 235 for YCBCRA).
.RE
.TP 3
.BR ilace= [ NONE | TOP_FIRST | BOTTOM_FIRST ]
Specify the interlacing used by the target stream. NONE, TOP_FIRST, and
BOTTOM_FIRST correspond to non-interlaced, top-field-first, and
bottom-field-first. The default if to match the source stream.
.br
If the source and target are both interlaced, but with different modes
(i.e. one is bottom-first, and the other is top-first), then \fBy4mscaler\fP
will convert one mode to the other by dropping the first source field.
.TP 3
.BR chromass= [ 420JPEG | 420MPEG2 | 420PALDV | 444 | 422 | 411 | mono | 444alpha ]
Specify the chroma subsampling mode to be used in the target stream.
The default is to match the source mode.
See "NOTES ON CHROMA MODES AND SUBSAMPLING" for more information.
.PP
.BI sar= N:D
.br
.BR sar= [ SRC | NTSC | PAL | NTSC_WIDE | PAL_WIDE ]
.RS 3
Specify the sample-aspect-ratio of the source stream. The value can either
be or numeric ratio (such as "10:11") or one of the keywords, which
correspond to the CCIR-601 values for 4:3 or 16:9 displays, respectively.
The keyword \fBSRC\fP specifies that the target SAR should match the source.
.RE
.PP
.BI scale= N/D
.br
.BI Xscale= N/D
.br
.BI Yscale= N/D
.RS 3
Set the scaling ratios, as a fraction; for example, scale=1/2. "scale=" sets
both X and Y factors simultaneously. "Xscale=" and "Yscale=" can be used to
set them independently.
.RE
.TP 3
.BR infer= [ PAD | CLIP | PRESERVE_X | PRESERVE_Y ]
Set the mode used to infer scaling ratios from active regions and SAR's.
The keywords are mutually exclusive. The default is PAD.
.TP 3
.BR infer= [ SIMPLIFY | EXACT ]
Set whether the above heuristic uses exact ratios, or whether it is allowed
to slightly adjust active regions to simplify the scaling ratios.
The keywords are mutually exclusive.
The default is SIMPLIFY.
.TP 3
.BR align= [ TL | TC | TR | CL | CC | CR | BL | BC | BR ]
Set the alignment point between the source and target active regions.
The keywords specify "top-left", "top-center", "top-right", etc.
The specified corner or point from the source region will be mapped to the
same spot in the target region; and cropping or padding which is applied
to the active regions will preserve this mapping. The default is CC,
for "center-center", i.e. the source and target regions are mutually centered.
The keywords are mutually exclusive.
The default is CC.
See "NOTES ON SOURCE AND TARGET ALIGNMENT" for details.
.PP
.BR preset= [ VCD | CVD | SVCD | DVD | DVD_WIDE | DV | DV_WIDE |
.br
.BR " " " " SVCD_STILL_HI | SVCD_STILL_LO | VCD_STILL_HI | VCD_STILL_LO |
.br
.BR " " " " ATSC_720P | ATSC_1080I | ATSC_1080P ]
.br
.RS 3
Use preset target parameters for several common output formats. Individual
parameters can be overridden by following with more "-O" settings.
These keywords are mutually exclusive. For the details of what settings
these preset keywords imply, see "NOTES ON TARGET PRESETS".
.TP 3
.BR VCD " - 352-wide VideoCD, progressive"
.TP 3
.BR CVD " - 352-wide (full-height) ChinaVideoDisc"
.TP 3
.BR SVCD " - 480-wide SuperVCD"
.TP 3
.BR DVD " - 720-wide DVD"
.TP 3
.BR DVD_WIDE " - 720-wide DVD, anamorphic pixels"
.TP 3
.BR DV " - 720-wide DV (bottom-field-first, 4:1:1)"
.TP 3
.BR DV_WIDE " - 720-wide DV, anamorphic pixels"
.TP 3
.BR SVCD_STILL_HI " - high-resolution SVCD still image"
.TP 3
.BR SVCD_STILL_LO " - low-resolution SVCD still image"
.TP 3
.BR VCD_STILL_HI " - high-resolution VCD still image"
.TP 3
.BR VCD_STILL_LO " - low-resolution SVCD still image"
.TP 3
.BR ATSC_720P " - ATSC 720p (progressive HDTV)"
.TP 3
.BR ATSC_1080I " - ATSC 1080i (interlaced HDTV)"
.TP 3
.BR ATSC_1080P " - ATSC 1080p (HDTV)"
.RE
.RE
.TP 5
.BI \-S " scaling_parameter"
.RS
Specify parameters for the scaling engine. All '-S' arguments are
evaluated in order, and later arguments on the command-line will override
earlier ones.
.TP 3
.B mode=MONO
Request monochrome scaling. The source is treated as monochrome and its
chroma channels are ignored. The chroma channels of the output
stream will be zeroed to yield a grayscale output.
.TP 3
.B mode=LINESWITCH
Request line swapping. Effectively, the top and bottom fields within each
frame will be swapped. This may help with malformed streams that have a
messed up spatial order. This option is only effective on interlaced streams.
.TP 3
.BI scaler= scaler-name
Use a particular scaling engine.
The available engines are:
.RS
'default' \- Matto's Generic Scaler (the default)
.RE
.TP 3
.BI option= scaler-option
Specify an option for the chosen scaling engine.
To see all the available options, use "option=help".
.RS 3
.PP
For the default engine, the available \fIscaler-option\fPs select the
filter kernel:
.RS 3
.TP 3
.BR box " - box filter"
.TP 3
.BR linear " - linear interpolation"
.TP 3
.BR quadratic " - quadratic interpolation"
.TP 3
.BR cubic " - cubic interpolation, Mitchell-Netravali spline"
.TP 3
.BR cubicCR " - cubic interpolation, Catmull-Rom spline"
.TP 3
.BR cubicB " - cubic interpolation, B-spline"
.TP 3
.BR cubicK4 " - Keys 4th-order cubic"
.TP 3
.BR sinc:N " - sinc with Lanczos window, N cycles"
.RE
.PP
To select kernels for the x and y scaling directions independently, use two
kernel names separated by a comma, e.g. \fIoption=box,quadratic\fP.
.PP
\fBsinc:N\fP will give the best quality results (least aliasing),
but is the slowest. The quality improves with larger values of N,
as does processing time.
\fBcubic\fP is generally regarded in the graphics world as the 3rd-order
cubic spline with the best trade-off between smoothing and aliasing.
\fBbox\fP yields the worst quality results (most aliasing), but is the fastest.
The default kernel is \fBcubicK4\fP, which has a flatter passband and
sharper cutoff than \fBcubic\fP. (It requires the same computational power
as \fBsinc:4\fP, but produces less ringing artifacts.)
.RE
.RE
.SH "NOTES ON TARGET PRESETS"
The following table details the settings provided by the various
target "preset=" keywords. When two values are given the primary
is for NTSC streams; the value in {braces} is for PAL streams.
If interlace value is unspecified, it is inherited from the source,
otherwise the indicated target interlacing is required.
.nf
Preset Frame Size Interlace SAR Subsampling
-----------------------------------------------------------------------
VCD 352x240{288} none 10:11{59:54} 4:2:0-JPEG
CVD 352x480{576} --- 20:11{59:27} 4:2:0-MPEG2
SVCD 480x480{576} --- 15:11{59:36} 4:2:0-MPEG2
DVD 720x480{576} --- 10:11{59:54} 4:2:0-MPEG2
DVD_WIDE 720x480{576} --- 40:33{118:81} 4:2:0-MPEG2
DV 720x480{576} bottom-first 10:11{59:54} 4:1:1
DV_WIDE 720x480{576} bottom-first 40:33{118:81} 4:1:1
SVCD_STILL_HI 704x480{576} none 10:11{59:54} 4:2:0-MPEG2
SVCD_STILL_LO 480x480{576} none 15:11{59:36} 4:2:0-MPEG2
VCD_STILL_HI 704x480{576} none 10:11{59:54} 4:2:0-JPEG
VCD_STILL_LO 352x240{288} none 10:11{59:54} 4:2:0-JPEG
ATSC_720p 1280x720 none 1:1 4:2:0-MPEG2
ATSC_1080i 1920x1080 (required) 1:1 4:2:0-MPEG2
ATSC_1080p 1920x1080 none 1:1 4:2:0-MPEG2
.fi
.SH "NOTES ON REGION GEOMETRY"
Active and matte regions are specified using a geometry string of the form
"WxH+X+Yaa". The "WxH" part specifies the size of the region, as a Width
and Height in pixels. (In some cases, the "WxH" may be omitted, and the
region size defaults to the full frame size.)
The "+X+Y" specifies the position of the region,
as an offset relative to the anchor point specified by "aa".
The "aa" code can be one of
.BR TL ", " TC ", " TR ", " CL ", " CC ", " CR ", " BL ", " BC ", or " BR .
These stand for "top-left", "top-center", ..., "bottom-center",
"bottom-right". These codes are not case-sensitive.
The "+X+Y" specifies the offset of the region's anchor point from the
frame's anchor point. For example, "+20+30TL" means that the top-left corner
of the region will be offset 20 pixels to the right and 30 pixels down from
the top-left corner of the frame.
The offset values can also be negative. For example, "-4+0CC" means that the
center (vertical and horizontal) of the region is offset 4 pixels to the left
of the center of the frame.
The default anchoring point for geometry strings is \fBTL\fP, i.e. the
top-left corner.
.SH "NOTES ON SOURCE AND TARGET ALIGNMENT"
Often, the source and target active regions do not match exactly.
This happens when, using the given or calculated scaling ratios, the
source region scales to a different size or shape than the target region.
In this case, the source and target regions are mutually clipped, so that
only the portion of the source which fits will be scaled into the target.
Before any clipping or padding, the source and target regions are aligned
so that the points specified via the "align=aa" parameter coincide.
The "aa" code specifies an anchor point as
described above.
For example, "align=BC" specifies that the bottom-center
of the source region should get mapped to the bottom-center of the target
region. In other words, the source region will be horizontally centered and
vertically aligned to the bottom of the target region before clipping:
.nf
---------------- source
|abcdefghijklmn|
---|opqrstuvwxyz01|--- target ----------------
| |234567890ABCDE| | |234567890ABCDE|
| |FGHIJKLMNOPQRS| | |FGHIJKLMNOPQRS|
| |TUVWXYZabcdefg| | |TUVWXYZabcdefg|
---------------------- ----------------
Before Mutually Clipped
.fi
If instead "align=TR" were centered, the source would be clipped in a different
place, and scaled into a different region of the target frame:
.nf
---------------------- ----------------
| |abcdefghijklmn| |abcdefghijklmn|
| |opqrstuvwxyz01| |opqrstuvwxyz01|
| |234567890ABCDE| |234567890ABCDE|
------|FGHIJKLMNOPQRS| ----------------
target |TUVWXYZabcdefg| source
----------------
Before Mutually Clipped
.fi
The default alignment mode is "CC", that is, the source and target are
mutually centered.
.SH "NOTES ON SCALE FACTOR INFERENCE"
If the X and Y scaling factors are not explicitly provided, \fBy4mscaler\fP will
infer the factors from the source and target active regions and sample
aspect ratios (SAR's).
If the active regions are not compatible shape-wise (given the SAR's),
the source and target regions will be clipped or padded
according to one of four policies. The policy is selected using
the "infer=" parameter and one of the keywords
.BR PAD ", " CLIP ", " PRESERVE_X ", or " PRESERVE_Y .
(The default is \fBPAD\fP.)
.RS 3
.TP 3
.B PAD
Pick scaling factors which will pad the source, but ensure that all of the
source image content ends up in the target.
.TP 3
.B CLIP
Pick scaling factors which will clip the source, but which will fill the
target region as much as possible.
.TP 3
.B PRESERVE_X
Pick scaling factors which preserve as much of the horizontal source content
as possible.
.TP 3
.B PRESERVE_Y
Pick scaling factors which preserve as much of the vertical source content
as possible.
.RE
.PP
The policy is further affected by a choice of two other keywords,
.BR SIMPLIFY ", or " EXACT .
(The default is \fBSIMPLIFY\fP.)
.RS 3
.TP 3
.B EXACT
Calculate exact scaling factors.
.TP 3
.B SIMPLIFY
Adjust the active regions and scaling factors (within 10% or so),
to simplify the ratios as much as possible. (For example, crop or pad
slightly to achieve a ratio of 2/1 rather than 45/22.)
.RE
.SH "NOTES ON CHROMA MODES AND SUBSAMPLING"
\fBy4mscaler\fP can convert streams from one chroma subsampling mode to another.
Such conversions are always lossy operations, even if the overall frame
is undergoing 1/1 scaling.
\fBy4mscaler\fP will infer the source's subsampling mode from tags in
the input stream header. The target presets
("preset=XXX") will attempt to set the target subsampling mode appropriately.
Otherwise, by default the target subsampling mode will match the source.
One can explicitly set the subsampling mode for the source and/or the target
by using the "chromass=" parameter.
\fBy4mscaler\fP is capable of reading and writing streams in the 4:4:4, 4:2:2,
4:1:1, and 4:2:0 (all three varieties) subsampling modes. The first three,
however, are a relatively new addition to the YUV4MPEG2
standard, and many MJPEGtools will fail to process them correctly, if at all.
smil2yuv and raw2yuv can produce native 4:1:1 streams from NTSC DV video,
which can then be converted to 4:2:0 by \fBy4mscaler\fP before further
processing by other tools.
If the source has an alpha-channel (i.e. 444ALPHA mode) and the target
does not, the alpha channel will simply be discarded. On the other hand,
if the target has an alpha-channel but the source does not, a constant
alpha-channel will be created using the alpha-value of the target's
background color (as set by "-O bg="). The default is fully-opaque.
Similarly, if the target has chroma channels but the source does not
(i.e. a luma-only MONO stream), then the chroma channels in the output
will be set according to the background color.
.RE
.SH "NOTES ON ANOMALOUS INTERLACE MIXTURES"
The YUV4MPEG2 format allows for "mixed-mode interlacing" streams, which may
contain a mixture of progressive and interlaced frames. Each frame is
tagged as temporally interlaced or progressive, and vertically-subsampled
frames (4:2:0 formats) are further tagged as spatially interlaced or not.
Unfortunately,
this allows for the possibility of \fBanomalous\fP frames, which happen
to be temporally interlaced (fields sampled at different times) but
spatially progressive (subsampling performed across entire frame), or
vice-versa.
The only reasonable thing to do with such anomalous frames is to
vertically-upsample the chroma, essentially making to problem go away
as quickly as possible.
\fBy4mscaler\fP will only process such frames if the target output format
is non-vertically-subsampled (e.g. 4:4:4, 4:2:2, etc.) and no
other vertical processing is required. Otherwise \fBy4mscaler\fP will
bail on processing in midstream when it encounters an anomalous frame.
If there is any possibility of encountering such an error, \fBy4mscaler\fP
will print a warning when processing begins.
.RE
.PP
.SH "EXIT STATUS"
.IP 0
Successful program execution.
.IP 1
Usage, syntax, or operational error.
.SH "AUTHOR"
This manual page is copyright 2005 by Matthew Marjanovic.
.br
Feel free to direct any questions, remarks, problems, or bug reports
concerning this tool to \fI<dmg @ mir.com>.\fP
.TP
For more info, see our website at:
.UR http://www.mir.com/DMG/
<http://www.mir.com/DMG/>
.UE
.TP
For more information on MJPEGtools, consult:
.UR http://mjpeg.sourceforge.net/
<http://mjpeg.sourceforge.net/>
.UE
.hw mjpegtools yuv2lav mpeg2enc ppmtoy4m yuvplay yuvscaler
.SH "SEE ALSO"
.BR mjpegtools (1),
.BR yuv2lav (1),
.BR mpeg2enc (1),
.BR ppmtoy4m (1),
.BR raw2yuv (1),
.BR smil2yuv (1),
.BR yuvplay (1),
.BR yuvscaler (1)
|