Model loading

docs/optics.md

@@ -368,6 +368,36 @@ geometry section. The target spacecraft, drawn after the bodies, uses the
 same depth buffer. So a target in front of Earth covers it, and a target
 behind Earth's limb is hidden.
 
+## The target model and its materials
+
+Code: `model.rs`.
+
+The target spacecraft is a triangle mesh loaded from STL or glTF. Each
+piece (an STL file, or a glTF primitive) is a part with one material, and
+for now a material is a Lambertian albedo spectrum, as for Earth and the
+Moon.
+
+Surface normals decide how bright each triangle is, through the cos(i)
+factor. STL files store a normal per triangle, but exporters often write
+zeros or wrong values, so the loader ignores them. It recomputes each
+normal from the order of the triangle's corners: counterclockwise as seen
+from outside. Every triangle is then lit as a flat facet, which matches the
+flat panels and boxes most spacecraft are built from. glTF files that store
+normals keep them.
+
+glTF describes a material's color as red, green and blue reflectances (its
+"base color"). Three numbers do not define a spectrum: very different
+spectra can look the same color to the eye. The loader turns them into a
+stepped spectrum, blue below 490 nm, green from 500 to 580 nm, and red above
+590 nm. That is a reasonable guess for painted surfaces seen by an RGB
+camera. It is a poor one for a camera whose channels differ from the eye's,
+or for anything in the near infrared, where the red value simply continues.
+For absolute radiometry of a real spacecraft, give the important materials
+measured reflectance spectra (M4 adds those, and BRDFs).
+
+STL has no units. CAD tools usually export millimeters, so loading a CAD
+model usually needs `scale: 0.001`. glTF is always meters.
+
 ## Not modeled yet
 
 | Effect | Where |