# fvoxel (Voxelflug Engine Pseudo 3D Heightmap)

reinhard@finalmedia.de
So 31. Mai 15:34:02 CEST 2026
Public Domain

## Step by Step

1. apt-get install ffmpeg imagemagick
2. Installiere fdraw
3. make
4. Siehe und verstehe start.sh
5. ./start.sh

## Spezifikation

Das minimalistische Tool erwartet Steuerbefehle auf stdin.
Im Gegensatz zu fdraw befehlen, sind das Großbuchstaben.
Das vermeidet dann auch Verwechselung.

Und mit diesen Befehlen werden keine Pixel gesetzt, sondern
eine Voxelwelt und Kamera im 3D Raum beschrieben.

Das Tool schreibt wiederum auf stdout einen bei bedarf kontinuierlichen 
zeilenbasierten strom an Befehlen für fdraw. 
Also befehlszeilen mit den kleinbuchstaben "r","m" und
"c" und "s" Befehlen von fdraw, um farbige Rechtecke zu zeichnen.
mit der fdraw dann diese Voxelwelt darstellen.

Dabei ist alles als Pipeline realisiert, sodass alle Befehle
und Modifikation der Voxelwelt und Kameraparameter von
stdin erfolgen, wodurch sie dynamisch skriptbar sind.

## fvoxel Engine Befehle

 M x y h r g b .......... Mapdatazeile x y heightmap_value(gray) color r, color g, color b setzen
 P x y h r p z .......... Position der Kamera auf der Map (x,y), Hoehe, Drehung, Pitch und Zoom setzen
 C r g b t n rn gn bn ... Colorcycling Slot definieren Originalfarbe (r,g,b), timedelay in ms, slotnumber, slot r,g,b 

Für alle Werte gilt... Buchstaben A-Z als Befehle
 
Jeweils positive Ganzzahlen.
Für Drehung ist es 0 bis 360 (als Gradangabe)
Für Pitch ist es 0 bis 360 (als Gradangabe)
Für Zoom ist es 0 bis 1000 (als Prozentuale angabe). Teleobjektiv höherer Wert, 100 ist Fischauge. 150 normal.

Damit kann man nun eine Terrain Map via stdin laden und eine Kamera positionieren.
Sobald eine Kameraposition gesetzt wird, wird der Frame und die Voxelwelt neu berechnet.

Dabei kann der Raum auch verändert werden, also man kann Berge, Täler und Flüsse
entstehen lassen oder auch die Vegetation und Schatten (Farbe) verändern, indem man 
einzelne M Befehle neu übergibt und die Kamera wieder setzt.  

## Hilfstools

Um aus bestehenden 1024x1024 png Hoehenkarten und passende M Befehle zu generieren genuegt eine einfache awk Zeile.

### Map-Dateien generieren falls nötig (mittels imagemagick)

colormap.png: PNG image data, 1024 x 1024, 8-bit colormap, non-interlaced
heightmap.png: PNG image data, 1024 x 1024, 8-bit grayscale, non-interlaced

	convert heightmap.png -compress none txt:- | awk -F'[(,):]' 'NR>1 {print $1, $2, int($4)}' > heightmap.txt
	convert colormap.png -compress none txt:- | awk -F'[(,):]' 'NR>1 {print $1, $2, int($4), int($5), int($6)}' > colormap.txt

### map.txt merged heightmap und colormap. Jede Zeile als "M" Zeile generieren

	paste heightmap.txt colormap.txt | awk '{print "M", $1, $2, $3, $6, $7, $8}' > map.txt

### Paletten-Analyse nach Haeufigkeit der Farben

	cat map.txt  | cut -d " " -f5,6,7 | sort | uniq -c | sort -n -k1


## Der RAM-Verbrauch (Arbeitsspeicher)
awk speichert Arrays als assoziative Hashmaps im RAM.

Eine 1024x1024 Map benötigt etwa 1 Mio Einträge. Das verbraucht ca. 70 bis 100 MB RAM. Unproblematisch.
Eine 4096x4096 Map benötigt 67 Mio Einträge. Das sind 4.5 bis 6 GB RAM. Problematisch.

Das Problem wäre mit chunk loading realisierbar, sodass wir gar nicht die ganze map von Anfang bereitstellen,
sondern abhängig von der Kameraposition dann vorausladen. Das kann durch ein separates Tool/Filter
in der Pipeline realisiert werden. Die Engine muss dazu nicht angepasst werden.