maszyna/tools/materials/README.md

# Norma materiałów

Wartości, przy których tekstury wyglądają poprawnie w shaderach opengl33 (`shaders/light_common.glsl`, GGX z roughness = 1 − G).
`validate_materials.py` sprawdza .mat i tekstury według tej normy.

Norma i opis niżej dotyczą shaderów z tej gałęzi (`fix/cab-lighting`: GTAO, parallax mapping, połysk z N·L, reflektory, `param_glossiness` jako wykładnik Phonga, ciemny metal). Na `master` shadery liczą jeszcze po staremu, różnice są opisane przy każdym punkcie. Wartości tekstur z tabel są dobre dla obu wersji, bo stare shadery różnią się tylko połyskiem przy niskim słońcu, reflektorami, `param_glossiness` i ciemnym metalem.

## Jak shader liczy piksel

- albedo = diffuse (sRGB) × kolor diffuse submodelu
- słońce rozproszone = 1.5 · (N·L)^1.25 · albedo · (1 − B)
- połysk słońca = GGX(roughness) · N·L · R · `param_specular`, dla metalu dodatkowo × albedo; bez Fresnela
- otoczenie = cubemapa(roughness) · EnvBRDF(F0, roughness) · alfa normalmapy · `param_reflection`, F0 = 0.04 dla niemetalu, albedo dla metalu; metal odbija co najmniej w połowie, niezależnie od alfy
- reflektory: rozproszone 1.35 · (N·L + 0.1) · albedo, połysk jak od słońca (GGX · N·L · R · `param_specular`)

Na `master` połysk nie miał N·L (przy niskim słońcu nie gasł), a reflektory mnożyły jasność przez (1 + `param_specular`).

## Kanały

| tekstura | kanał | znaczenie |
|---|---|---|
| diffuse | RGB | kolor (sRGB); dla metalu jego kolor odbicia |
| specgloss | R | siła połysku słońca, liniowo, mnożona przez `param_specular` |
| specgloss | G | gładkość, roughness = 1 − G (α = roughness²); `param_glossiness` ≥ 1 się skraca |
| specgloss | B | metal: 0 albo 1; metal nie ma diffuse, cały kolor bierze z odbicia; „metal” ciemniejszy niż liniowo 0.2 shader liczy częściowo, a poniżej 0.02 całkiem, jak lakier z R 0.06 |
| normalmap | RG | normalna (B pomijany, Z liczony) |
| normalmap | A | odbicie otoczenia; 255 tam, gdzie powierzchnia odbija, mniej tylko we wnękach |

## Wartości docelowe (`param_specular: 1`)

| materiał | diffuse sRGB | R | G | B |
|---|---|---|---|---|
| lakier nowy | kolor 40–230 | 15 (0.06) | 150–190 | 0 |
| lakier zużyty, brudny | kolor | 10–15 | 75–130 | 0 |
| plastik matowy (pulpit) | kolor | 13 | 75–115 | 0 |
| plastik błyszczący (gałki) | kolor | 15 | 150–190 | 0 |
| guma, wykładzina | 30–80 | 8–10 | 13–50 | 0 |
| tkanina, tapicerka | kolor | 5–10 | 0–40 | 0 |
| drewno lakierowane / surowe | kolor | 13 / 8 | 130–165 / 25–65 | 0 |
| szkło | – | 15 | 240–255 | 0 |
| stal goła | 170–200 szara | 255 | 130–180 | 255 |
| chrom, nikiel | 190–215 | 255 | 205–240 | 255 |
| aluminium | 225–245 | 255 | 100–180 | 255 |
| mosiądz / miedź | ~(245,228,175) / ~(250,209,194) | 255 | 130–205 | 255 |
| rdza, żeliwo, malowany metal | kolor | 10 | 25–75 | **0** |
| beton, tłuczeń, ziemia | kolor | 8–10 | 0–50 | 0 |

Zasady:

- `param_specular` = 1; siłę połysku niesie R.
- Niemetal: R·`param_specular` 0.02–0.12. R = 255 daje połysk ~17× za mocny; obniżanie G zamiast R tylko rozmywa odblask, a nie go ścisza.
- Metal: B = 255, jasny diffuse (liniowo ≥ 0.2, sRGB ≥ ~125) i alfa normalmapy wysoko. Ciemnego „metalu” shader nie zostawia czarnego, tylko liczy go jak lakier (diffuse wraca, połysk 0.06), a odbicie metalu ma co najmniej 0.5. Na masterze ciemny diffuse albo niska alfa dają czarny metal.
- Bez szumu w R, G, B i alfie normalmapy: w słońcu iskrzy.

## Shadery bez specgloss

| shader | roughness | połysk słońca |
|---|---|---|
| brak `shader:` / `default`, `reflmap` | 0.04 (lustro, tylko otoczenie × `param_reflection`) | brak |
| `normalmap`, `parallax`, `detail_*`, `shadowlessnormalmap`, `sunlessnormalmap`, `default_detail` | (2 / (`param_glossiness` + 2))^¼ jak wykładnik Phonga: 10 (domyślnie) → 0.64, 75 → 0.40, 1000 → 0.21 | `param_specular` · (r+g+b)/2 diffuse |
| `rain_windscreen` | zawsze 0.04 | `param_specular` · (r+g+b)/2 diffuse |

Na `master` `normalmap`, `parallax` i `detail_*` miały roughness 1 − 1/`param_glossiness` (większa wartość = bardziej matowo), a `shadowlessnormalmap`, `sunlessnormalmap` i `default_detail` zawsze 0.04. Walidator rozpoznaje obie wersje z plików shaderów.

## Walidator

Wymaga Pythona 3 z `numpy` i `Pillow` (`pip install numpy pillow`).

```
python3 tools/materials/validate_materials.py <katalog z assetami> [podkatalogi...] [opcje]
python3 tools/materials/validate_materials.py ~/pctga dynamic --fallback <katalog gry> --shaders <repo>/shaders --csv wyniki.csv
```

| opcja | znaczenie |
|---|---|
| podkatalogi | co sprawdzić względem katalogu z assetami, domyślnie `dynamic`; może być węższe, np. `dynamic/pkp/sa103` |
| `--fallback DIR` | drugi katalog gry, w którym szukać tekstur, których nie ma w pierwszym (można podać kilka razy) |
| `--shaders DIR` | shadery, według których liczyć; domyślnie `shaders/` z tego repo. Gdy gra ma inne shadery niż repo, podaj jej katalog `shaders`, żeby ocena zgadzała się z tym, co widać w symulatorze |
| `--csv FILE` | wyniki do pliku CSV: material, shader, poziom, opis |
| `--info` | pokazuje też informacje, nie tylko błędy i uwagi |
| `-j N` | liczba procesów, domyślnie wszystkie rdzenie; cały pctga trwa ok. 80 s |

Wynik: dla każdego materiału z problemem ścieżka `.mat`, shader i lista komunikatów, na końcu podsumowanie.

- `BLAD` – trzeba poprawić (np. połysk niemetalu kilkanaście razy za mocny, brak tekstury, nieistniejący shader).
- `UWAGA` – prawie na pewno źle wygląda (lustro na niemetalu, ciemny metal, szum w specgloss).
- `info` – tylko z `--info`, rzeczy do wiadomości.

Walidator czyta pliki shaderów i z nich rozpoznaje, co każdy shader robi ze specgloss, `param_glossiness`, `param_specular` i `param_reflection`, więc działa i dla starych, i dla nowych shaderów.

### Jak poprawiać

1. Uruchom walidator na swoim katalogu pojazdu, np. `dynamic/pkp/sa103`.
2. Najpierw `BLAD`: zwykle R w specgloss (niemetal ok. 15/255) albo `param_specular` (zostaw 1, siłę połysku daje R).
3. Potem `UWAGA`: G (gładkość) według tabeli wartości docelowych, B tylko 0 albo 255, metal z jasnym diffuse.
4. Poprawiaj źródłowe TGA i uruchom walidator jeszcze raz. Z TGA będą robione tekstury BC7, które zastąpią obecne DDS, więc poprawki w DDS przepadną.