README.md

README.md 6.1 KiB Download Raw

1	# Paperdoll Renderer
2
3	Desktopeditor voor `.ppd`-projecten, modelimport en een geanimeerde 3D-preview.
4
5	## Starten
6
7	Rust 1.96.0 staat in `rust-toolchain.toml`. Op Debian/Ubuntu gebruik je voor bouwen en het venster `pkg-config`, `libxcb1-dev`, `libx11-dev`, `libxkbcommon-dev`, `libxkbcommon-x11-dev` en `libgl1-mesa-dev`. De native filepicker gebruikt XDG Desktop Portal met een GTK/KDE-backend, of Zenity. Live 3D vereist OpenGL 3.3.
8
9	```bash
10	cargo run
11	cargo run -- "/pad met spaties/character.ppd"
12	cargo run -- --preview-fixture
13	cargo run -- --status
14	```
15
16	## Project en bodies
17
18	Het startvenster biedt Project laden en Nieuw project, beide met een systeembestandkiezer. Nieuw project maakt `character.ppd` en de mappen `assets/body/`, `assets/equipment/`, `presets/`, `cache/` en `renders/`. De CC0-testlichamen worden in `assets/body/` voorbereid. `--preview-fixture` maakt een tijdelijk voorbeeldproject en opent de mannelijke body.
19
20	De eerste projectweergave toont de bodies. Kies man / Kies vrouw selecteert een model. Een extern bestand wordt naar de projectmap gekopieerd; bij een bestaande naam krijgt de kopie een eigen naam. Modellen met bijbestanden kun je met hun relatieve mappenstructuur in de projectmap zetten en daar selecteren. Importoverzicht toont meshes, materialen, textures, joints en clips van glTF/GLB, FBX en OBJ+MTL.
21
22	Open man / Open vrouw opent de body. Een geskind glTF/GLB-model is in de live preview zichtbaar:
23
24	- Sleep om te orbiten, scroll om te zoomen. Een 24-bits depthbuffer zorgt dat voorste oppervlakken achterliggende delen afdekken.
25	- Kies een animatieclip en gebruik Pauze / Speel.
26	- Yaw − / Yaw + volgen twaalf hoeken van 30°; pitch -30 / 0 / 30 kiezen de hoogte. Yaw 0 kijkt naar de voorkant van de testlichamen (−Z).
27	- Render maakt een gekleurd PNG-stilbeeld van de huidige pose en camera in `renders/body-male-still.png` of `body-female-still.png`. De preview toont achtereenvolgens de hoge resolutie en de ingestelde doelresolutie, met nearest-neighbor uitvergroot en een voortgangsbalk. Iedere pass behoudt zijn beeldverhouding en staat gecentreerd met zwarte balken waar nodig. Live 3D keert terug naar het model.
28	- Stel breedte, hoogte en fps in de Bodies-weergave in.
29
30	![Bodyweergave met animatie- en camerabediening](docs/screenshots/body-live.png)
31
32	## Equipment en opslaan
33
34	Vanuit een body opent Equipment de lijst. Kies een definitie of Nieuw.
35
36	1. Geef een unieke naam van maximaal 64 kleine letters/cijfers/`-`/`_`, zonder spaties; `body` is gereserveerd.
37	2. Kies Man / Vrouw voor het lichaam dat je bekijkt; Geldig voor bepaalt op welke geslachten het preset van toepassing is.
38	3. Onderdeel toevoegen (OBJ) opent de systeembestandkiezer. Rigide OBJ-onderdelen worden inclusief MTL en relatieve PNG-bijbestanden ingesloten. De preview gebruikt diffuse kleur/texture en alpha-cutout (grens 0,5). Bronbestanden mogen de modelmap niet verlaten.
39	4. Vouw Skeleton / botten uit en kies het doelbot. Stel relatieve positie XYZ en rotatie XYZ in graden in (Rz·Ry·Rx). Het onderdeel beweegt met dat bot tijdens walk/attack of een andere geïmporteerde bodyclip. Iedere sekse heeft een eigen botbinding; de numerieke offsets zijn gedeeld.
40	5. Kies shinymap (PNG) moduleert de instelbare glanssterkte. Wis shinymap keert terug naar een uniforme glanssterkte. Vul desgewenst Herkomst / licentie in. Meerdere onderdelen kunnen verschillende botten gebruiken.
41	6. Opslaan bewaart het project plus zelfbevattende binaire `.ppe`-snapshots in `presets/` (geometrie, bronpayloads, materialen/textures, transformaties, bindingen, seksevlaggen en herkomst). Er worden geen bronpaden buiten het project nodig om die opnieuw te laden.
42
43	Preset importeren leest een `.ppe` uit bijvoorbeeld een ander project. Bij een andere rig moet je de botten opnieuw kiezen; er wordt niet stil geretarget. Onvolledige configuraties kunnen worden opgeslagen, maar onopgeloste onderdelen worden niet op een gegist bot getekend. Verwijder onderdeel haalt een onderdeel uit het werkpreset; Verwijder equipmentdefinitie haalt de definitie uit de projectlijst. Oude project-snapshots blijven voor herstel bewaard. Opslaan vereist een bestandssysteem met hardlinks; bij een fout wordt een bestaande snapshot niet overschreven.
44
45	Een preset is begrensd op 32 MiB, 32 onderdelen/bestanden en textures van maximaal 2048×2048. Een project heeft maximaal 64 presets en 64 MiB aan presetbestanden. De volledige containerbeschrijving staat in `design.md`.
46
47	```bash
48	# Zelfbevattend CC0-zwaardvoorbeeld in een nieuw tijdelijk project
49	cargo run --example equipment_fixture --locked
50	```
51
52	![Werkelijke equipment-editor met geanimeerd lichaam en handgebonden OBJ](docs/screenshots/equipment-live.png)
53
54	Bij sluiten of Ander project / Nieuw project met wijzigingen kies je Opslaan, Niet opslaan of Annuleren. Als opslaan mislukt, blijft het project open. Annuleren in de bestandkiezer behoudt je huidige werk.
55
56	## Openen met
57
58	- Windows: start de uitgepakte `.exe` eenmaal om de editor voor het huidige account aan Openen met toe te voegen. Kies daarna bij een `.ppd` Openen met → Paperdoll Renderer (of selecteer de `.exe` via Bladeren).
59	- Debian/Arch: de pakketten installeren de `.ppd`-MIME-koppeling, desktopstarter en iconen. Kies de editor in Openen met.
60	- Linux AppImage/losse binary: bewaar het bestand op zijn vaste plek en voer `"/pad/Paperdoll.AppImage" --install-desktop` uit. Hiervoor zijn `shared-mime-info` en `desktop-file-utils` nodig. Daarna staat de editor in Openen met. Herhaal dit na verplaatsen van de AppImage.
61
62	Het venster, de Linux-starter en de Windows-executable gebruiken Tims applicatie-icoon.
63
64	## Tests
65
66	```bash
67	cargo fmt --check
68	cargo check --workspace --all-targets --locked
69	cargo clippy --workspace --all-targets --locked -- -D warnings
70	cargo test --workspace --locked
71	# Linux GPU-regressie (Xvfb + Mesa): echte overlappende geometrie en pixelreadback
72	xvfb-run -a cargo run --example preview_depth_probe --locked
73	```
74
75	De testlichamen komen uit `scripts/generate_test_bodies.py`. Het FBX-testbestand wordt met Blender via `scripts/convert_test_body_to_fbx.py` gemaakt.