Welcome to LPub, a LEGO construction step documentation generator. LPub reads in DAT and LDR files you create with LDRAW/MLCAD, runs it through L3P and POV-Ray and produces step by step construction images. LPub produces images that show the parts you need to add to your assembly, and then produces images of your partial assembly with the parts added.
POV-Ray is an image renderer that uses a grahpics technique called ray tracing to produce realistic high quality images . L3P, by Lars Hassing, converts LDRAW DAT/LDR files to POV-Ray format so POV-Ray can render them.
LDRAW and MLCAD are Computer Aided Design (CAD) programs that let you enter your LEGO designs into the computer so you can record how you built your construction. LDRAW supports the concept of construction steps. As you enter parts into the design, you can add pause steps. After you've entered your design, you can play back the construction step by step.
LPub reads in your construction steps and produces an image of the model's construction at each step. LPub also produces a pictures that show the parts that you will need to complete each step. All this image generation is completely automatic.
LDRAW supports the idea of sub-assemblies or sub-models, where parts of a large design can each be entered into their own DAT file. The final assembly of the design can be described by combining the sub-assemblies. LPub supports this concept by producing construction and part list images for each step of sub-assemblies. Part list images in the final assemblies contain small images of the sub-assemblies.
LDRAW supports a mechanism called Multiple Part Description, or MPD, where you can have subassemblies and assemblies all described in the same file. Currently LPub does not support MPD files.
LDRAW provides two kinds of steps: steps with rotation and steps without.
Steps with rotation are very handy, especially for LPub. MLCAD gives you four views on your design: top, left, front and birds-eye. With any of these views, parts can be added that cannot be seen in the view. LPub creates its images from the birds eye view, above and to the side of the model. If you add parts that are in the back, bottom or the far side of the model, they may not be visible from the birds eye view. Using rotation steps, you can turn the model around, or over so you can see where the parts are added.
There are four kinds of rotation steps: rotate absolute, rotate relative, rotate additive and rotate end. Currently LPub only supports rotate relative and rotate end. The other rotations will be supported as I figure out how to make them work.
LPub can create web-pages that walk you through the sequence of assembly and sub-assembly construction steps. This is a nice way to glue all your images together into one publishable document for others to use.
INSTALLATION
LPub uses L3P and POV-Ray to create the images for your construction. Given that LPub needs these other programs to do its job, LPub installation is a bit complicated. I've described the installation steps in Appendix A.
OPENING LDRAW FILES
Use the "File->Open DAT" menu item to open a DAT or LDR file for processing. Once you've selected your file and clicked OK, LPub checks all the parts in your design against LDRAW's known part list. LPub displays any missing part names, and the file that uses them. LPub will not process designs with missing parts.
CONFIGURING OPTIONS
Although LPub has a graphical user interface (GUI) you really don't do much work to get LPub to create your images. You use LPub's GUI mostly to configure the way you want your output to look. LPub was originally written to help me create artwork for a Constructopedia type book that I co-authored, thus the name LPub (LEGO Publisher).
LPub can create high resolution pictures needed for printing books, or screen resolution images for web pages. LPub can support bitmap images (for publishing) or JPEG images which typically have a much smaller file size than their bitmap version. LPub has many options that you can configure before you start it generating images. All the options are accessable using the Options dialog. You can bring up the Options dialog using the "Tools->Options" menu item.
The Options dialog lets you configure three kinds of options: Output Mode options, Construction Image options, File management options, and Configuration file handling.
OUTPUT MODE OPTIONS
The most important aspect of Output Mode is deciding whether you want to create web pages, or published book qaulity imagery. The default is web pages. This means that the images will have lower resolution (less pixels), will be in color, and will be created in JPEG format. You can also chose to use print resolution, which also gets you a default file format of bitmap, and LPub operates in black and white mode.
Once you select the resolution, you can override the default file format by clicking the format buttons. This allows you to use bitmaps on web pages, or JPEG format for publishing.
POV-Ray produces images in bitmap format. If you decide you want to use JPEG format, LPub converts the images to JPEG format. By default, LPub erases the bitmaps assuming they are no longer needed. If you want to keep the bitmap images, uncheck the box labeled "Erase Bitmaps after conversion".
When converting files from bitmap to JPEG, you can use the scroll bar named "JPEG Quality" to control how nice your JPEG images look. The higher the quality, the closer the image quality is to bitmap quality, but the files tend to be larger files produced with low quality. You can use the "JPEG Quality" scroll bar to make trade offs between quality and file size.
When producing print resolution documentation, you have to option to make LPub operate in black and white mode. LPub, does not produce black and white images (it assumes the publisher will convert them to black and white.) When in black and white mode, LPub puts color labels on the parts in the part list images. This is so that readers know what colored parts to use if the book is printed in black and white.
CONSTRUCTION IMAGES OPTIONS
When you select a documentation resolution using the Output Mode Resolution buttons, LPub sets you up with a default file size. The Construction Images Dimensions fields let you override the default. For print resolution the default is 2048 pixels wide and 1536 pixels tall. For screen resolution the default is 800 pixels wide and 600 pixels tall.
LPub supports de-emphaisizing parts added in previous steps so it is easier to tell what is new for this step. MLCAD does the same thing. LPub calls this process color scaling. Using the "Previous Step Color Scaling" controls, you can control the amount of color scaling and the scaling color. The amount of scaling is controlled by the scroll bar. The scaling color is controlled by the color button to the right of the scroll bar. You can change the scaling color by clicking on the color button and using the color dialog provided.
The color scaling scroll bar controls how much of the scaling color is put into the parts from previous steps. When the slider in the scroll bar is all the way to the left, previous step part colors are unchanged. When the slider is all the way to the right, the previous steps' parts colors are ignored completely and only the scaling color is used. When the slider is not at either extreme, the previous steps parts' colors are a proportional mixture of part color and scaling color.
FILES OPTIONS
The Files Option lets you override the default behavior of create files, use files and discard files. The default behavior is to erase the generated DAT and POV files when they are no longer needed. You can use the files option to keep those files around.
The option "Run POV-Ray" controls whether POV-Ray is run after .POV file generation. The default is to run POV-Ray. Disabling this creates the step .DAT and .POV files, but does not run POV-Ray, this is primary used for debug of POV file generation problems.
The option "Run POV-Ray only if needed" controls when POV-Ray is run. Normally LPub only creates images that do not exist or need to be remade because their DAT file changed, or some failure made LPub fail to generate images previously. This can save time by not creating images that have already been created. When this option is unchecked, POV-Ray is always run. This mode is primarily for debug.
You may be trying to create LPub documentation from DAT files you got off the internet. This means that the DAT files may try to use parts that you do not have installed for LDraw. This can cause serious problems for LPub, so by default, LPub checks for this. You can uncheck the "Check DAT(s) against Part List" option if you want to prevent this check from happening.
CONFIGS OPTIONS
LPub lets you save your option configurations into files. LPub supports to kinds of config files: global and local. The global config file is read when you first start up LPub. When checked, the "Auto load local configs" option makes LPub read in directory (and presumably model specific) options from the local configuration file. Otherwise LPub uses the global configurations.
Local configs let you have design specific option configurations. I use this feature to configure designs for books to have print quality settings and designs that are for web page publishing use screen quality settings.
CREATING IMAGES
Now that you have configured LPub the way you want, you can create your images. Use the "File->Open DAT" menu to access to open a DAT or LDR file. LPub checks design to make sure that you have all the LDRAW parts you need before it lets you generate images. If some parts do not exist, their names are displayed and dialog is displayed explaining there was a problem.
Use the "Step Images->All Images->Include Sub-assemblies" menu to start the image generation process. At this point you might want to go away an let your computer process for a couple hours. Really, it can take quite a while to generate all the images.
When your images are done, you can use the "Web Pages->Screen Web Pages" menu item to create a web page. If your DAT file is named robot.dat, the first page of youe construction images is named robot_00.html.
The pages have links to go to the next or previous step, or back to the first page.
PART IMAGE GENERATION
There are a few files external to LPub that help control the part image generation process. These files are installed in the Part_Images subdirectory of the LPub installation directory.
The first file is called orientation.ldr. If a part image comes out with an orientation you do not like, you can add the part to orientation.dat using LDRAW or MLCAD. The orientation you give the part in these CAD tools is the orientation LPub will use to create part images.
A second file is called half_size.ldr. The parts that listed in half_size.ldr will be rendered at half the normal size. This is useful for extremely large parts like the RCX, micro-scouts and long beams.
A third file is called color_annotation.ldr. When LPub is operating in black and white mode, it puts a color label above the parts in the part list images, so you can tell the color parts to add. This does not make sense for complicated parts like the RCX, motors, since they typically only come in one color. Adding a part to color_annotation.ldr prevents it from getting the color labels.
PART IMAGE DATABASE
The part image databases are a place where LPub keeps images of individual parts. The databases are simply directories that contain images of parts of a specific color. They reside in the installed LPub subdiretory called Part_Images. The color print resolution sub-directory is called 1600x1200. The black and white print resolution sub-directory is called 1600x1200_bw. The screen resolution sub-directory is called 640x480.
If a part is rendered in a way you do not like, add or adjust its orientation in orientation.ldr. If it is too large, add it to half_size.ldr. If it gets a color label and you do not like it, add the part to the color_annotation.ldr.
After making these adjustments, look through approriate part image database directory and remove the image you do not like. The part type and color is encoded in the file name of the image. The format of the file name is:
part_[type]_[color]_crop.bmpwhere [type] is the part type, and [color] is the part color. You can look at the DAT file that uses the part in question to find the part typoe and color, if you do not know it. The part type is the last parameter of a part usage line (you need to not use the suffix .DAT or .LDR). The color is the second parameter on a part usage line (it is a number).
Next time you render your design, LPub will recreate the part that you deleted.
RENDERING ONLY SOME IMAGES
The "Step Images->All Images->No Sub-assemblies" will make LPub create images only for the DAT that you opened, even if that DAT references other DATs in the same directory.
The "Step Images->Construction Images->Include Sub-assemblies" will create construction images for all steps in your DAT, and steps for any DATs that your top level DAT references. It does not create part list images.
"Step Images->Construction Images->No Sub-assemblies" produces construction images only, and only for steps in the DAT you opened.
The "Step Images->Part List Images" menu produces only the part list images for your model. You can do this for sub-assemblies as well as just for the DAT you opened.
APPENDIX A - INSTALLING LPUB
LPub requires four external programs to complete its job: LDRAW/MLCAD the CAD programs, perl, a script based programming language POV-Ray, a ray tracing image renderer, and L3P, a program that converts DAT files for use with POV-Ray.
To acquire, LDRAW and MLCAD use this link
Follow the instructions in this step by step tutorial.
To acquire L3P, use this link:
When the L3P zip file is downloaded, extract L3P.EXE.
To acquire POV-Ray, use this link:
Click on the DOWNLOAD, select the Windows version of POV-Ray, and follow the directions to install. LPub was written and tested against POV-Ray 3.1. Version 3.6 of POV-Ray was recently released, but LPub has not been tested against this version.
CREDITS AND DISCLAIMERS
LPub is copyrighted and is the property of Kevin L. Clague. LEGO us the trademark of the LEGO Corporation. LPub is legally not associated with LEGO. LPub is not authorized, sponsored, or legally associated with the LEGO Corporation in any way.
Trademarks and copyrights of the tools used by LPub (L3P and POV-Ray) are properties of their respective owners.
MLCAD is the property of Micheal Lachmann who has so wonderfully devoted his talents to the LEGO Community. You can get MLCAD and documentation at his site.