ref: 84d01c3ac4bae4ddae787c298f49ac96957d372a
dir: /readme/
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