# ColorMatrix v2.5

## Přehled

autor: tritical
verze: v2.5
stáhnout: http://bengal.missouri.edu/~kes25c/
kategorie: Různé pluginy
requirements:

- YV12 & YUY2 Barevné prostředí

licence: GPL

## Popis

ColorMatrix v2.0 je založen na původním filtru ColorMatrix od Wilberta Dijkhofa.

Při převodu RGB do YUV a naopak, existuje více sad koeficientů, které je možné použít. Nejběžnější jsou Rec.709, FCC, Rec.601 (aka SMPTE 170M nebo ITU-R BT.470-2), a SMPTE 240M. Účel filtru ColorMatrix je přepočítat hodnoty YUV videa, které bylo převedeno z RGB použitím jedné sady koeficientů na takové hodnoty na jaké by měly být převedeny z RGB při použití jiné sady koeficientů. Důvod proč je to užitečné je ten, že některé MPEG-2 streamy typicky používají Rec.709, zatímco většina počítačového softwaru (XviD/DivX dekodéry, atd...) předpokládají Rec.601. Proto, pokud berete MPEG-2 stream použitím Rec.709 a předáte ho jako YUV do dekodéru, který nadvzorkuje do RGB použitím Rec.601 , barvy budou mírně mimo. V takovém případě by jste mohli použít ColorMatrix pro převod videa z Rec.709 do Rec.601 a jeho předání dekodéru. Další příklad je, pokud zachytáváte video softwarem, který používá Rec.601 a pak chcete enkódovat do MPEG-2 použitím enkodéru, který předpokládá Rec.709.

Na první pohled by se zdálo, že ke splnění svého úkolu by ColorMatrix potřeboval vnitřně převést na RGB použitím zdrojových koeficientů a pak převést zpět na YUV použitím nových koeficientů. Ale není to tento případ. To co Colormatrix ve skutečnosti dělá, je přepočítání inverzní matice (matrix) zdrojových koeficientů (dává matici pro provedení YUV->RGB) a pak násobí takovou matici novou maticí koeficientů. To dává sadu koeficientů pro provedení převodu přímo z YUV do YUV.

ColorMatrix podporuje YV12 a YUY2 barevná prostředí, a umí převádět mezi Rec.709, FCC, Rec.601, a SMPTE 240M. ColorMatrix je také schopen provádět rozšíření a zúžení rozsahu ([16,235/240]->[0,255] nebo [0,255]->[16,235/240]) jako část převodu colorimetrů nebo jako samotné.

### Syntaxe

`ColorMatrix` (clip, string "mode", int "source", int "dest", int "clamp", bool "interlaced", bool "inputFR", bool "outputFR", bool "hints", string "d2v", bool "debug", int "threads", int "thrdmthd", int "opt")

### Parametry

mode:

Může být řetězec jako `"source->dest"`, kde `source` a `dest` jsou každý nahrazen jedním z následujících (velká písmena nevadí):

- Rec.709
- FCC
- Rec.601
- SMPTE 240M

Příklady:

- ColorMatrix(mode="Rec.709->Rec.601")
- ColorMatrix(mode="Rec.601->FCC")
- ColorMatrix(mode="SMPTE 240M->Rec.601")
- ColorMatrix(mode="Rec.709->FCC")

source a dest nemohou být stejné jestliže inputFR a outputFR jsou také stejné.

výchozí - "" (string)

source:

Umožňuje nastavit zdrojový formát v celočíselné formě. Pokud je zadán parametr mode, tak přepíše source. Možná nastavení:

- 0 - Rec.709
- 1 - FCC
- 2 - Rec.601
- 3 - SMPTE 240M

Parametry source a dest nemohou být stejné jestliže inputFR a outputFR jsou také stejné.

výchozí - 0 (int)

dest:

Umožňuje nastavit cílový formát v celočíselné formě. Pokud je zadán parametr mode, tak přepíše dest. Možná nastavení:

- 0 - Rec.709
- 1 - FCC
- 2 - Rec.601
- 3 - SMPTE 240M

Parametry source a dest nemohou být stejné jestliže inputFR a outputFR jsou také stejné..

výchozí - 2 (int)

clamp:

Zadává jestli by mělo být použito pre/post oříznutí s omezením na 16-235/16-240. Možná nastavení:

- 0 - bez oříznutí
- 1 - oříznutí před (klipu vstupujícího do ColorMatrix)
- 2 - oříznutí po (klipu vystupujícího z ColorMatrix)
- 3 - oříznutí před i po

3 je to, co používaly předchozí (v1.x) verze ColorMatrix.

výchozí - 3 (int)

interlaced:

Prokládané video YV12 vyžaduje zvláštní zacházení... takže pokud je vaše video YV12 a je prokládané, potřebujete nastavit tento parametr na true. Jinak ho nechte na false. Pro prokládané zpracování vstupního klipu v ColorMatrix nesmí být klip založen na polích (fieldbased). Pokud je, ColorMatrix vyhodí chybu, která to ukáže a řekne, že by jste měli před tím použít AssumeFrameBased().

výchozí - false (bool)

inputFR:

Říká ColorMatrix jestli je vstupní video v plném rozsahu [0-255] nebo v omezeném rozsahu [16-235/240]. Toto nastavení nemá žádný efekt, jestliže je nastaveno stejně jako outputFR. Hodnota true indikuje plný rozsah a false indikuje omezený rozsah.

výchozí - false (bool)

outputFR:

Říká ColorMatrix jestli vysílat plný rozsah [0-255] nebo omezený rozsah [16-235/240] YUV hodnot. Toto nastavení nemá žádný efekt, jestliže je nastaveno stejně jako inputFR. Hodnota true indikuje plný rozsah a false indikuje omezený rozsah.

výchozí - false (bool)

hints:

DGDecode v1.20 nebo novější může vysílat údaje (hints) colorimetry ve video streamu které může ColorMatrix číst, aby automaticky určil zdrojové koeficienty. Pro zapnutí tohoto, nastavte `info=3` v `mpeg2source()` a nastavte `hints=true` v `ColorMatrix()` jak je ukázáno níže:

    Mpeg2source("F:\TestStreams\avs\AguileraGrammies.d2v", info=3)
    ColorMatrix(hints=true)

Pokud by jste rádi zobrazily info o colorimetrech, použijte `info=1` v `mpeg2source()` jak je ukázáno níže:

    Mpeg2source("F:\TestStreams\avs\AguileraGrammies.d2v", info=1)

Pokud není ColorMatrix schopen detekovat údaje hints ve streamu (například protože používáte nesprávnou verzi dgdecode) vyhodí chybu. Při používání hints=true, převod zadaný parametrem mode (nebo source a dest pokud není nastaven mode) bude aplikován jen když colorimetry vstupního videa neodpovídají cílovým colorimetrům. Například, pokud je mode nastaven na "Rec.709->Rec.601" (nebo je mode ponechán prázný a source=0 a dest=2), pak převod bude použit pouze pokud colorimetry vstupního videa nejsou už "Rec.601". Pokud už odpovídají colorimetry vstupního videa cílovým colorimetrům, pak jsou snímky předány nedotknuté (kromě případu kdy omezení clamp>0 nebo pro rozsah převodu kdy inputFR a outputFR nejsou stejné). Které scénáře nastávají vidíte při použití debug=true.

výchozí - false (bool)

d2v:

Novější verze DGIndexu (v1.20+) zapisují informaci o colorimetrech do d2v projektového souboru. ColorMatrix je schopen provést rozbor d2v souboru a automaticky určit zdrojové koeficienty z této informace. Pro zapnutí této možnosti, nastavte parametr d2v roven cestě a jménu d2v projektového souboru jak je ukázáno níže:

    Mpeg2source("F:\TestStreams\avs\AguileraGrammies.d2v")
    ColorMatrix(d2v="AguileraGrammies.d2v")

Pokud je d2v soubor umístěn v jiné složce než Avisynth skript budete muset zadat plnou cestu. Operace filtru, když je parametr d2v zadán je stejná jako s hints=true. Pokud colorimetry vstupního videa už souhlasí s cílovými colorimetry zadanými v parametru mode (nebo v source a dest), pak převod není aplikován. Pokud colorimetry nesouhlasí, pak je převod aplikován. Použití parametru d2v je rychlejší než použití hints.

Je možné, že se colorimetry v klipu měni. Pokud je to tento případ, pak možnost d2v bude pracovat jen když neprovádíte střih - trim() nebo nepřeuspořádáte snímky (například ivtc) před výzvou ColorMatrix. Pokud ColorMatrix detekuje, že colorimetry v d2v souboru se mění, bude žádat, aby čísla snímků zadaných v d2v souboru byl roven číslům snímků ve vstupním klipu. Možnost hints nemá toto omezení.

Pro lidi, které to zajímá, je to tento (a následný) řádek(ky) v d2v souboru

    800 5 0 8210 0 0 32 32 92 b2 b2 a2 b2 b2 a2 b2 b2 a2

Zvýraznil jsem informaci o colorimetrech tučně. Viz Colorimetry pro vysvětlující informace.

výchozí - "" (string)

debug:

Pokud je nastaven na true, vysílá se ladící (debug) informace přes OutputDebugString(). Můžete použít utilitu DebugView ze Systeminternals pro prohlížení této informace. Informace zahrnují detekované údaje (hints), použité rutiny (c, mmx, nebo sse), atd...

výchozí - false (bool)

threads:

Nastavuje počet vláken, která Colormatrix použije pro zpracování. Může být jakákoli hodnota větší než 0 a, pro YUY2, menší než výška snímku, pro YV12, menší než výška snímku dělená 2. Je-li nastaven na 0, ColorMatrix automaticky detekuje počet volných procesorů a nastaví threads rovno této hodnotě.

výchozí - 1 (int)

thrdmthd:

Určuje jak bude snímek rozdělen mezi pracující vlákna, když je threads větší než 1. Možnost 0 rozdělí snímek na sousední díly (každé vlákno bude zpracovávat blok řádků výška/threads). Možnost 1 rozdělí snímek na nesousední díly (každé vlákno bude zpracovávat každý threads - ový řádek).

výchozí - 0 (int)

opt:

Kvůli zaokrouhlování rozdílů, výstup z mmx a sse2 rutin (přítomné jen pro YV12) není přesně stejný jako výstup z c rutin (c rutina je přesnější). Maximální rozdíl mezi simd a c rutinami je +-1 na plochách Y/U/V . Rutiny mmx a sse2 vytváří srovnatelný výstup. Pokud nastane rozsah převodu (inputFR a outputFR jsou různé), tak se použijí jen c rutiny. Parametr opt je zahrnutý do vypnutí použití simd optimalizací, jestliže to chcete. Možná nastavení:

- 0 - vynutí c rutinu
- 1 - vynutí mmx rutinu
- 2 - vynutí sse2 rutinu
- 3 - auto detekce

výchozí - 3 (int)

## Colorimetry

Toto je seznam všech možností v souladu s MPEG-2 specifikacemi a DGDecode. Sloupec úplně vpravo ukazuje jak GSpot zkrátí každou položku.

0 | zakázaný | N/A
1 | ITU-R BT.709 | I709
2 | Nespecifikované video (neznámé) | N/A
3 | rezervováno | N/A
4 | FCC | FCC
5 | ITU-R BT.470-2 (přesně stejné jako ITU-R BT.601) | I470
6 | SMPTE 170M (přesně stejné jako ITU-R BT.601) | S170
7 | SMPTE 240M | S240
8-255 | rezervováno | N/A

** Doporučení BT.601 je aktualizací BT.470-2

## Informace na pozadí

Existuje několik způsobů jak převést YUV stream na RGB. Ten nejznámější používá Rec.601 koeficienty. Ten je například použit v rutinách převodů barev AviSynthu, VirtualDubu a XviD/DivX. Při přehrávání XviD/DivX je stream převeden na RGB použitím Rec.601 koeficientů. Hlavním problémem je, že občas jsou použity jiné koeficienty pro převod YUV do RGB (další dva jsou koeficienty Rec.709 a FCC koeficienty). Problém nastává pokud je stream enkódován použitím jedné sady koeficientů (například Rec.709 koeficientů pro mnohé dvd streamy), a někde v řetězci překomprimování-zpracování-přehrávání je předpokládána odlišná sada koeficientů (Rec.601 koeficienty pro XviD/DivX dekodér nebo FCC koeficienty pro TMPGEnc/QuEnc nebo Rec.709 koeficienty pro CCE). Tak získáte mírně deformované barvy, což vypadá jako změna ve světlosti (ve skutečnosti to není změna světlosti, barvy jsou prostě trochu mimo).

Jak poznáte, která sada koeficientů je použitá při enkódování MPEG-2 streamu? Občas jsou koeficienty uchovány v hlavičce MPEG-2 souboru (pole "matrix coefficients" v "sequence display extension"). Novější verze GSpot bude schopná přečíst tuto část hlavičky, ale také DGDecode (s Mpeg2source(info=1)) může být k tomuto použit. Pokud toto rozšířené pole není přítomno v hlavičce MPEG-2 souboru, specifikace říká, že předpokládáme použití výchozích Rec.709 koeficientů.

## Odkazy

- uživatelé oznamují problém - obdržení jiné světlosti při porovnání avs skriptu s přímým otevřením mpeg2 ve VDubMod.
- informace na pozadí - vlákno na doom9 o tomto problému.
- pole "matrix coefficients" specifikuje sadu koeficientů danou v Tabulce 6-9 z ISO/IEC 13818-2, část 6.3.6 (Rec.709 není zcela správná).
- ITU-R_BT.709 - můžete získat tři bezplatná doporučení na platné emailové adresy.

## Seznam změn

v2.5, 25th January 2009
+ Updated d2v parsing to correctly determine frame count for v16 DGIndex project files.
- Fixed a bug causing the mmx/sse2 routines for FCC<->Rec.601 conversions to give incorrect U plane output.

v2.4, 18th January 2009
- Fixed a bug causing the sse2 routines not to process the last (width&15) pixels, and the mmx routines not to process the last (width&7) pixels.

v2.3, 08th January 2008
- Calculate conversion coefficients for PB/PR rows from luma coefficients
- Added inputFR and outputFR parameters allowing for YUV range expansion/contraction
- Changed the clamp parameter from bool to int to allow specifying only pre clipping or only post clipping or both

v2.2, 28th August 2007
- Changed the integer scaling parameter to a boolean parameter named clamp (scaling 1/2 were redundant)
- Fixed source==dest error when using d2v or hints
- Fixed thrdmthd being switched internally (i.e. backwards versus the behaviors described in the readme)

v2.1, 18th January 2007
+ Added multithreading support (the threads and thrdmthd parameters)
- Don't invoke AssumeFrameBased() internally during interlaced processing (requires that the input clip be framebased)

v2.0, 12th October 2006 (Changes from v1.10)
+ Rewrote a large portion of the code
+ Added ability to convert between any of: Rec.709, FCC, Rec.601, and SMPTE 240M
+ Added source and dest parameters
+ Added scaling parameter (optional clipping and unscaled coefficients)
+ d2v option supports changing colorimetry info (with trim() and frame rearrangement restriction)
- fixed a problem with calculated luma values that were < 0 being set to 255 instead of 0

`Český překlad:11.6.2009`