INTRODUCTION
This is version 1.0.0 of l2rib, a utility which, in conjunction with a RenderMan compliant renderer, can be used to generate pictures from LDraw (http://www.ldraw.org/) models. In other words, it reads .DAT files, and writes RIB files which can then be rendered by renderers such as PhotoRealistic RenderMan.
l2rib was written by Julian Fong. Please see l2rib.C for disclaimer and license.
l2rib's home page is: http://www.levork.org/l2rib.html
FEATURES
- draws tris (command 3) and quads (command 4)
- draws lines (command 2 and command 5, currently only with PRMan or equivalent renderer that supports Procedural DSO primitives)
- supports (actually, requires) color definitions (0 !COLOUR), by default read from ldconfig.ldr
- generates highly optimized RIB for efficient occlusion culling (requires the renderer implement DelayedReadArchive Procedural correctly); raytracing and shadow map passes contain proper visibility and disabled shaders for fast rendering
- all subparts are cached for speed of future invocation (requires renderer implements user attributes and options correctly)
- detects and substitutes prebuilt RIB chunks to support higher level geometry. The provided substituions replace conic sections with RiCylinders, RiSpheres, and RiTori; round edges with bezier RiCurves; disc cutouts with trimmed RiNuPatches
- allows specification of camera orientation, light source position/intensity/color/shadow generation type, background color, quality settings
- automatically writes out RIB for rendering depth map shadows
BUILDING
MacOS example:
env RMANTREE=/Applications/Pixar/RenderManProServer-21.7 make -f Makefile.unix
INSTALL
The zip or tar archive will uncompress into an "l2rib" directory. This directory contains the l2rib binary, the l2rib source code, and data files used at render time (prebuilt RIB files, shaders, and shared libraries). The directory can be moved or renamed to whatever you want; you will need to supply the name of the directory to l2rib itself.
In the l2rib installation directory under shaders, you will find a "lego.tif" file. If you want to use the -studlogo flag, which causes the Lego logo to appear on studs, you will need to generate a "lego.tx" file using the texture conversion program appropriate to the renderer. For example, if you are using PhotoRealistic RenderMan, you would run
txmake lego.tif lego.tx
You will also need to create a writable directory for temporary RIB files, which will be generated by l2rib during conversion. A preexisting temporary directory such as /tmp on UNIX or C:\tmp on Windows will work just fine.
You should now run the l2rib binary from where you installed it, without any options. When l2rib is run for the first time, it looks for an initialization file in a certain directory: $HOME/.l2ribrc on UNIX, and l2rib/l2rib.ini under your application data folder on Windows. If this file does not exist, l2rib will ignore your command line options and instead prompt for interactive input and ask for 3 configuration settings:
LDraw directory:
In ini: ldrawdir=directory
This is the directory under which the p, parts, and
model directories containing LDRAW .dat files are
located.
l2rib directory:
In ini: l2ribdir=directory
This is the path to the l2rib directory which you
unarchived.
Temporary cache:
In ini: cachedir=directory
l2rib writes out one RIB file per DAT referenced
directly or indirectly in your model; this is done for
efficiency reasons, since it avoids having a single
monstrous RIB file, and also allows the renderer to
use the DelayedReadArchive RiProcedural, which can
lead to significant gains in speed. These RIB files
need to be stored in a directory until actual
rendering takes place, after which they can be deleted
or reused by future l2rib sessions.
As an example, here's what happens when I run l2rib on my UNIX machine:
l2rib Configuration file not found - running initial configuration. Enter LDraw directory (parts are under this folder): /home/jfong/ldraw Enter l2rib installation directory: /home/jfong/l2rib Enter temporary cache file directory: /tmp Configuration complete.
And on my Windows 2000 machine:
F:\l2rib>l2rib Configuration file not found - running initial configuration. Enter LDraw directory (parts are under this folder): \woody\jfong Enter l2rib installation directory: \woody\jfong\l2rib\prebuilt Enter temporary cache file directory: c:\tmp Configuration complete:
Note in particular the filename conventions used on the different platforms. Both UNC paths and normal filenames are legal in the Windows case.
After the interactive configuration, the initialization file will be created with the three directory settings in key=value form. You may edit these settings later, or add default l2rib options as described below.
You are now ready to create RIB files for rendering.
USAGE
l2rib [options] file
l2rib takes a .DAT or .MPD file as input, and generates a RIB file as output. If a .MPD file is used as input, multiple RIB files will be written into the current directory, one for each subpart, and the main RIB file will be main model.
l2rib accepts various options which modify the output RIB stream, which in turn determine various settings seen in your output render. These options are flags passed on the command line; many options can also be set in the initialization file using a key=value syntax. Note that the center of the model will be at the origin, hence all camera and light positions will also be relative to this origin.
-bgcolor r g b
In .ini: bgcolor=r g b
Sets the background color of the rendering. If not
set, the default color of white (1.0, 1.0, 1.0) will
be used.
-camerafrom x y z
In .ini: camerafrom=x y z
In combination with the camerato value, this
determines the vector along which the camera will be
pointed. Note that the camera will not necessarily be
placed here (because of the cameradistance setting).
If not set at all, the default camera view vector will
start at (-1, -1, -1).
-camerato x y z
In .ini: camerato=x y z
In combination with the camerafrom value, this
determines the vector along which the camera will be
pointed. If not set at all, the default camera will
point at the origin (0, 0, 0).
-cameraup x y z
In .ini: cameraup=x y z
Sets the camera up vector. If not set at all, the
default camera will have an up vector of (0, -1,
0). (This is "up", in LDraw space.)
-cameradistance distance
In .ini: cameradistance=distance
Specifies a multiplier for the camera distance. This
value is multiplied with the distance equal to the
radius of the smallest sphere which encloses the
object bounding box to determine how far from the
origin the camera will be placed.
-colorconfig file
In .ini: colorconfig=file
Specifies a color config file which will be read
prior to generating output. This file should contain
lines of the form "0 !COLOUR ...", and will define
the mappings from LDraw colors to RIB material
definitions. If not present, l2rib will default
to ldrawdir/ldconfig.ldr.
Note: LDraw supports the MATERIAL syntax of the
!COLOUR and will inject the given value directly
into the RIB stream. This is a useful way of
creating custom shader definitions for LDraw
color codes.
-file
No .ini equivalent
By default, l2rib will create a RIB which renders
directly to the framebuffer device. Turning on the
-file option causes l2rib to generate RIB which
renders to the TIFF display driver. The resulting TIFF
file will have the same basename as the input .dat
file, with a .tif extension.
-floor scale
In .ini: floor=scale
Setting this option will cause l2rib to create a large
square polygon immediately below your model. The scale
is a number which is multiplied with the distance
equal to the radius of the smallest sphere which
encloses the object bounding box to determine the size
of one side of the square. If this is not set, no
floor will be created.
-format x y
In .ini: format=x y
Specifies the pixel size of the final rendered
image. If not set, a default 640x480 will be used.
-light x y z r g b i mode
In .ini: light=x y z r g b i mode
Can be repeated multiple times
Each -light option creates a distant light source at
coordinates (x, y, z) in world space, with color (r,
g, b), and an intensity of i. "mode" can be one of the
following:
map: A shadow map will be created and generated for
this light. This means that a depth map will
be rendered from the point of view of the
light prior to the render, and then that map
will be used to generate shadows. Only
useful with PhotoRealistic RenderMan.
cache: Assumes that a shadow map already exists and
uses it. This map should have been created
with the "map" option as above.
none: No shadows will be generated for the light.
raytrace: Shadows will be determined by raytracing.
Only useful for raytracing implementations
which accept "raytrace" passed to the shadow()
shadeop.
If no lights are specified at all, then a single
default light at (-1, -1, -1) with color (1, 1, 1),
intensity 1, and casting no shadows will be added to
your scene, i.e. equivalent to:
-light -1 -1 -1 1 1 1 1 none
-lines
No .ini equivalent
The -lines flag tells l2rib to output directives into
the RIB stream to draw lines, using the Procedural
geometry defined in line.so (or line.dll on Windows).
This requires a renderer which implements the Optional
RiProcedural "DynamicLoad" correctly and can also
handle RiCurves. By default, this is disabled.
-nocache
No .ini equivalent
Indicates that l2rib should not use cached RIB files
from previous usage. By default, l2rib will reuse all
RIB files that exist in the cache directory; specify
nocache if you want l2rib to regenerate these files
instead. This is necessary if the underlying DAT files
have changed for some reason.
-o filename
No .ini equivalent
Write RIB into the specified output file instead of on
standard output (the default).
-pixelsamples s
In .ini: pixelsamples=s
Sets the pixel samples. Geometric antialiasing is
usually done in RenderMan by supersampling and
filtering the samples. This option controls how many
samples will be taken per pixel in each direction,
i.e. setting it to 4 will mean 16 supersamples per
pixel. If unset, the default pixelsamples is 2.
Typically this doesn't need to be set to a high
setting unless you are using the -lines option.
-raytrace
In .ini: raytrace
Determines whether the output RIB file should contain
directives allowing the scene to be raytraced. By
default, l2rib determines the visibility attributes
of your geometry relative to raytracing by checking
whether any lights call for raytracing. This flag
overrides that determination, which is useful if
you intend to take the output RIB file and manually
add raytracing shaders to it.
-shadingrate r
In .ini: shadingrate=r
Sets the shading rate. Shading rate measures how many
pixels between shading samples in each direction,
i.e. a shading rate of 1.0 means the renderer will
shade about once per pixel, while a shading rate of
0.25 means the renderer will shade 4 times per pixel.
This parameter has the greatest effect on quality
versus speed; keep in mind that unless you are using a
shader with fine detail (and plastic is _not_ such a
shader), you can usually get away with a shading rate
of 1.0 or even more, resulting in much faster
renderings. Keep in mind that pixel samples is
decoupled from shading rate in RenderMan. 1.0 is the
default shading rate if left unset.
-shadowformat size
In .ini: shadowformat=size
Specifies the pixel size of the shadow maps to
use. Increasing the pixel size may increase the
quality of mapped shadows, especially if your format
setting is also large. Only one dimension needs to be
specified (since shadow maps should be square), and
the dimension should be a power of two. If not set, a
default of 1024x1024 will be used.
-studlogo
In .ini: studlogo
By default, studs do not show the Lego logo. This flag
causes the logo to appear as a displacement on studs.
This option uses the basicDisp shader and requires
"lego.tx" to also exist.
BUGS
This software is under active development. If you have any bugs or feature requests, please feel free to direct them to me. Contact information for the author can be found at http://www.levork.org/contact.html