Feature #233

suggestions for manual and discoverability

Added by William Newman over 4 years ago.

Status:NewStart date:01/28/2014
Priority:NormalDue date:
Assignee:-% Done:


Target version:-


(mitsuba-0511b4b0db3a.zip jan 2014)

The default scene lighting uses a setting ("extend") which doesn't
seem to be documented in the manual. It would be nice if instead the
implicit default settings could easily be turned into equivalent
explicit settings as a starting point for experimentation and

It would be nice if (1) code snippets in the manual could be fed
to Mitsuba verbatim and/or (2) it was straightforward to discover the
defaults and/or explicit settings that made them work. For example,
pasting the example in "8.1.1 Cube intersection primitive (cube)" into
a scene file and rendering of course won't work. A systematic manual reader
will know that wrapping it in <scene version="0.4.5"> is needed, but
then it still produces unexpected output (staring into one of the
faces of the cube at close range). And even after fixing this with a
transform, it is not so easy to figure out what explicit lighting
settings correspond to the default settings. The code to render the
illustrations in the manual must already exist somewhere; it would be
helpful if it were systematically linked to the illustrations so that
the reader could look at it. (E.g., a relative path-to-xml-file within
the Mitsuba source tree appended to the caption of each figure.)

Somewhat relatedly, log output like
WARN ren0 [Scene] No emitters found -- adding sun & sky.
would be even more useful if it printed the XML specification
for what it was doing (which from skimming the 'No emitters found'
section in the source code is definitely not equivalent to adding
all-default constructs like <emitter type="sunsky"/> to the scene
file). And if it's too fiddly and tedious to give the full
specification of what it's doing, it would be an easy improvement to
make the warning text more explicit: s/sun & sky/sun & sky (using
unrealistic settings which help increase the efficiency of path
tracing)/. That kind of explicit runtime description of defaults is
probably unsuitable for defaults such as materials, where the default
might be used dozens of times in some scenes; in such cases, it would
be helpful to describe the default at the head of the appropriate
manual section. (E.g., in the introduction to the "8.3 Textures"
section, a paragraph like "In Mitsuba, every shape necessarily has a
texture; if no texture is specified in a scene, the default <texture
type="bitmap"> <string name="filename" value="mighty-lurker.jpg">
</texture> is used to help the shape look more like part of an

Also available in: Atom PDF