3D Environments in Plan 9

You will need:

	• libgeometry (ships with 9front)
	• libgraphics
and
	• libobj

`mk pulldeps` should take care of everything.

TOOLS

	- vis: a scene visualizer
	- med: a model editor (WIP)
	- solar: a solar system planetarium (WIP)
	- obj: an OBJ to model(6) conversion tool

USAGE

	vis [-s] [-t picfile] [-g wxh[xs]] model...

	The s option will switch the skybox on (performance will drop
	considerably).
	The t flag takes as input an image(6) file used to texture the first model.
	The g flag takes as input the dimensions of the camera viewport.  If it's
	smaller than screen the image will be upscaled to fit it as much as
	possible, otherwise it will default to the screen dimensions.
	The models supported by the program are model(6) files.  You can find
	examples in the mdl/ folder (those with a .mdl suffix).

	NOTE:	Now two visibility determination technologies are available: the
		Z-buffer and the A-buffer. To get the best results out of them the
		following configurations are recommended:

		- z-buffer: blend OFF | z-buf (depth testing) ON  | a-buf OFF
		- a-buffer: blend ON  | z-buf (depth testing) OFF | a-buf ON

	- move camera with ↑↓ ((for|back)ward), ←→ (horizontally), PgUp and PgDn (vertically).
	- rotate camera with AD (yaw), WS (pitch), QE (roll).
	- change cameras with F[1-4]. cameras 1 and 3 are orthographic, 2 and 4 perspective.
	- to zoom in and out use Z and X respectively, also mouse ScrUp and ScrDn.
	- to show the HUD with stats and context information press H.
	- pressing RMB shows a shader selection menu.
	- pressing MMB shows a menu with a variety of controls.
	- holding down the LMB while moving the cursor will change the scene orientation.
	- to quit press Del.

	Vis also has a hidden option, ι, which enables inception mode.
	Use it wisely, or you might never come back.


	med

	- move camera with ↑↓ ((for|back)ward), ←→ (horizontally), PgUp and PgDn (vertically).
	- rotate camera with AD (yaw), WS (pitch), QE (roll).
	- to zoom in and out use Z and X respectively, also mouse ScrUp and ScrDn.
	- to show the HUD with stats and context information press H.
	- pressing RMB shows a menu to select shaders and add primitives/solids.
	- pressing MMB shows a menu to control the texture samplers.
	- holding down the LMB while moving the cursor will change the scene orientation.
	- to quit press Del or select "quit" from the MMB menu.


	solar [-ms]

	The m option enables museum mode.  In this mode the planets and sun will
	spawn along the x-axis, as close to each other as their sizes allow, so
	you can move through them more easily.
	The s option will switch the skybox on (performance will drop
	considerably).

	- move camera with ↑↓ ((for|back)ward), ←→ (horizontally), PgUp and PgDn (vertically).
	- rotate camera with AD (yaw), WS (pitch), QE (roll).
	- to zoom in and out use Z and X respectively, also mouse ScrUp and ScrDn.
	- to show the HUD with stats and context information press H.
	- pressing MMB shows a menu to control the movement speed.
	- point at a body and click LMB to select it.
	- to quit press Del or select "quit" from the MMB menu.

	In addition to the key controls, there are three buttons in the command
	box, at the bottom of the screen:

	- look at: pressing LMB will show a menu with a list of
		planets to choose from.  Select one and release, and the camera
		will focus on it.
	- go to: pressing LMB will show a menu with a list of planets
		to choose from.  Select one and release, and the camera will go to
		a close enough point outside of it.
	- date: when not in museum mode, the location for each of the
		planets will be pulled from NASA's Horizons API ephemerides for
		the current date.  Click on it and enter a new date—with the same
		format—to grab the ephemerides from that date and update planet
		positions.


	obj [objfile [dir]]

	This tool will take a Wavefront OBJ file objfile, with all its materials,
	and convert it into a model(6) file (see libgraphics/model.6.txt) that's
	written, along with its assets, inside the directory dir.

	If no dir is specified, it writes the model(6) to stdout.  And if no
	arguments are given, it reads the OBJ file from stdin.

CUBEMAPS

	The skyboxes for vis and solar are stored in the cubemap/ folder.  To use
	them you first have to convert them from JPEG to image(6), using the
	helper script (conv) available in each of them.

	% for(d in cubemap/*)@{ cd $d && conv }

MODEL CONVERSION GUIDE

	Some of the models that come with the repo (mdl/) were already converted
	from OBJ to model(6), but many remain untouched.  To convert an OBJ model
	into its model(6) counterpart run the following:

	% $O.obj mdl/goku/goku.obj mdl/goku

	You can also create a temporary folder to hold them while you work with them:

	% ramfs -p
	% mkdir /tmp/goku
	% $O.obj mdl/goku/goku.obj /tmp/goku

	If the model is made out of multiple files, like in mdl/vivi/, you have to
	convert the different .obj files one by one.  Each will create a main.mdl
	that you need to rename; here's an example script to automate the process:

	% for(o in mdl/vivi/*.obj){
		$O.obj $o /tmp/vivi
		mv /tmp/vivi/main.mdl /tmp/vivi/`{basename $o .obj}^.mdl
	}

	Then you should be able to visualize them as usual:

	% $O.vis /tmp/vivi/*.mdl