Welcome to LPub, an LDraw compatible tool for publishing your LEGO creations. LPub reads in LDraw files created with LDraw compatible design entry tools, runs them through L3P to convert them to POV-Ray format, and runs POV-Ray to create photo-realistic images of your design.
Here are some highlights of LPub:
- Supports DAT, LDR and MPD (multi-part-DAT) files
- Support for LDGLite
- Support for LDView
- Support for POV-Ray 3.1 and MEGAPOV 0.7
- Support for POV-Ray 3.5 and MEGAPOV 1.0
- Support for POV-Ray 3.6 and MEGAPOV 1.0
- PNG file format with Alpha channel
- Integrated LSynth support
- Can produce single image of completed assembly
- Can produce a sequence of images and web pages that show step by step construction
- Produces partially assembled models with previous step's parts ghosted
- Produces part list image for parts used in each step
- Produces Bill of Materials image
- Produces two kinds of web pages showing construction steps
- Graphics user interface to most L3P options
- Graphics user interface to many POV options
- Page layout mechanism for generating complete building instructions
The root of all LEGO CAD tools is the LDraw file format created by the late James Jessiman. He defined a simple, yet powerful file format for LEGO design descriptions. He made the format for LDraw files open to the public. Upon James' passing away, LDraw.org was created, a central resource for LDraw related tools.
Michael Lachmann wrote a Windows based CAD entry program called MLCad which is quite widely used. He made some of his own extensions to the LDRAW format that are quite popular.
Lars Hassing wrote a program called L3P which converts LDRaw based designs into a file format that can be used by POV-Ray, a ray tracing program that creates stunning imagery. Lars has done a number of things with L3P that make it powerful and easy to use.
POV-Ray is an image renderer that uses a graphics technique called ray tracing to produce realistic high quality images.
LPub combines the power of LDRaw files, L3P and POV-Ray under one graphics user interface tool. LPub stands for LDraw Publication. I originally wrote LPub to automate the creation of step by step building instructions from LDraw files for book by Syngress Publications. INSTALLATION
To install and get LPub working you need a number of tools from the internet. The required and optional tools and how to install them are listed in Appendix A.
LPUB MENUS
LPub's simple menu includes File, Generate, and Help.
FILE MENU
The File menu lets you control LPub's access to data and configuration files. The Open LDraw File menu lets you open an LDR, DAT or MPD file for publishing.
Between LPub, L3P, POV-Ray and MEGA-POV there are lots of options you can configure. LPub lets you save these options to a file so that you do not have to reconfigure LPub to the desired settings each time you start it up. LPub lets you save these settings globally or locally. Saving options globally is a way to set the default options every time you bring up LPub. Local options can be used on a directory by directory basis, so they can be tailored to a specific LDraw design.
The Save Global Config menu saves the current settings in the LPub installation directory. Next time you start up LPub this configuration will automatically loaded. The Save Local Config saves the settings in the current directory in a file called config.lpb. Next time you open an LDraw file in that local directory, the local configuration will be restored automatically. The Save Config As... lets you save the config file using the name you choose.
The Open Global Config menu can be used to restore your overall defaults, in case you made configuration changes you didn't like. The Open Local Config menu can be used to restore your local defaults. The Open Config File lets you open any configuration file you want.
The Exit menu makes LPub shut down POV-Ray and itself.
GENERATE MENU
The Generate menu lets you create images and web pages needed to publish your LDRAW designs.
The Complete Assembly menu makes LPub create a image of your model ignoring any step information in your model.
The CSI,PLI and BOM menu lets you create step by step construction images. This process creates two kinds of files for each step: construction step images (CSI), and part list images (PLI). This operation can take a very long time because LPub has to run POV-Ray once for each step in your design. When you use the "CSI,PLI and BOM" menu a Cancel dialog is displayed. It contains a progress bar showing you how much work has completed and how much work remains. The progress bar is updated each time POV-Ray completes an image. The file bring rendered is also displayed in the status bar at the bottom of the LPub main window. You can cancel this long operation using the Cancel button.
Once your images are generated, you can use the CSI Web Pages menu to create and display web pages that lead you step by step through the construction steps.
The Layouts menu lets you merge your CSI and PLIs together to make a set of building instructions, made up of pages. The layout process is controlled by meta-commands inside your LDraw file. The layout process is described in more detail later.
Once your layout pages are generated, you can use the Layout Pages menu to create and display web pages that lead you page by page through the building instructions.
The Web Page Table menu creates a tabular form of web page that is tailored specifically for Syngress Publishing.
UTILITES MENU
LPub creates a large number of files as part of the process of creating your building instruction images. All the files that LPub creates are placed in the directory that contains your LDraw model (this directory is referred to as the current working directory.) LPub creates a sub directory in the current working directory, call LPub. Under the LPub directory, LPub creates these sub-directories:
- LDraw - contains LDraw format files - POV - contains generated POV-Ray files - Images - contains generated CSI and PLI files - Parts - contains generated part image files - Layout - contains generated building instruction pages - HTML - contains generated web pages.
The Utilities menu provides menus for erasing all files generated by LPub.
The Erase CSIs and PLIs menu erases all the CSI and PLI images in the Images directory.
LPub maintains a Part Image Cache to eliminate rerendering of individual parts used to create PLIs. When you change rendering settings associated with PLIs, LPub erases the cached part images automatically. If something is broken in this process, you can manually erase these files using the Erase Part Images Cache menu.
The Erase Layout Images menu erases all the files in the Layouts directory.
The Erase HTML Images menu erases all the files in the HTML directory.
Please use care with the erase menus, because they will erase all the files in the associated directory, whether LPub created them nor not. Do not manually create your own files in these directories, because they will also be erased by the erase menu.
The Min Camera Distance tells you how close you can place your camera to your model, and have all your CSIs rendered at the same scale.
HELP MENU
The Help menu LPub Documentation menu brings you to this document in your default web browser. The About menu displays LPub's About box.
COMPLETE MODEL
LPub provides a user interface to simplify the production of POV-Ray images from your LEGO designs. The simplest operation it can perform is to create an image of your design completely model. To do this, follow these steps:
- Use the File > Open LDRAW File menu item to locate the file you want rendered - Use the Generate > Complete Assembly menu item to create a POV-Ray imageIf all works correctly, you should see LPub fire up POV-Ray and render the file. If you run into trouble, consult Appendix B for trouble shooting techniques.
A simple change to your result would be to use L3P's floor option to place a floor under your design. Follow these steps:
- Select the L3P tab in the Configuration section of LPub's main window - This gives you a set of tabs for L3P options. - Select the Surroundings tab. - In the Floor panel, click the Enable button to enable a floor.Now use the Generate > Complete Assembly menu to regenerate your image with a floor.
CSIs,PLIs and BOM
When entering a design using MLCad, you can add steps. MLCad can play back your assembly showing you all the parts added before each step. This is very handy for other people who want to recreate your models in real LEGO using your LDraw designs. MLCad can also create a sequence of images for you showing each step.
LPub takes this concept further by creating photo-realistic images of each construction step (Construction Step Images, or CSI), as well as creating images that show the parts used in each step (Part List Images or PLI). This page from real LEGO Instructions shows a single CSI containing beams and pins. This is the CSI. The page also contains a box with parts and part counts. LPub calls this a PLI.
LPub also supports the concept of a callout. A callout is a small composite image of s small part made of a few steps. These LEGO Instructions use a single callout to show the assembly of a gearbox before it is added to the model.
LPub provides a method for gathering your CSIs, PLIs, and callout images into pages in a set of building instructions. This process is called layout.
LPub can also generate a visual list of all the parts used in the model, called a bill-of-materials, or BOM. BOMs are like PLIs, except they are for the entire model. Most LEGO building instructions do not have BOMs, and for those that do, the format has changed over the years. The format that LPub generates is similar to the format used by the LEGO Mindstorms Constructopedia. (Look at the last page).
LPub can then create a sequence of web pages that shows each construction step in order. You can publish these on the web, and people who know nothing about LEGO CAD can find out how to build your models.
To create a sequence of construction images for your design, use the Generate > CSIs, PLIs and BOM menu. LPub will analyze your design, create a bunch of DAT files (one per step), and start POV-Ray off drawing pictures for each step in your design. After it has completed all the CSIs, POV-Ray will start drawing pictures of each of the parts used in your design. LPub uses those pictures to create PSIs for each step in your design.
When LPub completes rendering all your CSIs and PLIs, use the Generate > Layouts menu to merge them into a sequence of building instruction pages. The layout process is a powerful tool for merging together your CSIs and PLIs into advanced building instruction pages comparable to what LEGO produces. The Layout process is controlled by meta-commands you place in your LDraw file. The meta-commands used for layout are described in LAYOUT section. I created building instructions for one of my MOCs called pedmatic. One of my Brickshelf Folders contains the LDraw file, background file and the resulting building instruction pages.
When LPub completes creating all your pictures, use the Generate > Screen Web Pages menu to create your pages and view them using your internet browser.
The first web page shows a picture of your complete assembly. It provides a link to the first construction step. The construction step pages provide links to the next step, previous step or the first page of the sequence.
CONFIGURING OPTIONS
The LPub configuration is broken down into three major option groups: Building Instructions, Renderer, and HTML. You can use the tabs at the top of the Configuration section to select between these option groups. Within each group there is a set of tabs breaking options down by subject. The next few sections describe the options's organization and meanings.
BUILDING INSTRUCTIONS OPTIONS
LPub's big strength is creating imagery for "Building Instructions". Most of the controls for Building Instructions are on the Building Instructions tab. Building Instructions options are primarily related to the format and look of construction step, part list images and Bill Of Materials.
GENERAL CONTROLS
The Global tab provides the most important controls for generating building instruction images. The Generate > CSI, PLI and BOM menu generates construction images, part list images and a bill of material image. The Generate panel contains check boxes that allow or disallow generation of any of these images.
The Scale panel provides controls that directly affect the renderers used to generate your images. LPub performs two kinds of renders, the construction image and part images used in part list images and bill of materials. LPub provides render controls specifically for each kind of render. The controls include render window width and height, plus camera lens and orthographic controls, as well as distance controls.
Left to their own devices, the renderers LPub uses would draw the images so they fill the render window. As the model gets larger, step after step, the renderers tend to move the camera farther and farther away from the model, so it can be wholly enclosed in the render window. As the camera distance gets larger the rendered size of a given brick gets smaller and smaller. This is change of size is undesirable. LPub provides Scale controls to eliminate this change of scale.
The Scale controls provide a minimum distance that the camera can be placed from the model. LPub uses L3P to translate LDraw files into POV files. Part of the L3P process is to calculate the camera distance needed to wholly enclose the model in the window. If the camera distance provided by L3P is smaller than the Distance value provided, LPub substitutes the calculated distance with the Distance value.
The Distance value needed to wholly enclose the model depends on the model dimensions and the characteristics of the camera lens. The Utilities > Min Camera Distance menu item examines the distance needed for every step in the model and sub-models. It reports the maximum of the camera distances of each of the steps. If the reported distance is used as the Distance value, then all the steps in the building instruction images will have their bricks rendered at the same scale.
PREVIOUS STEP COLOR SCALING
LPub allows you to enhance the parts that are added in the current step, by deaccentuating the parts added in previous steps. It does this by letting you modify the color of bricks added in previous steps. LPub gives you two controls to modify the previous steps' brick colors: an alternate color, and a factor that lets you mix the bricks' color and alternate color. With the factor at zero (scroll bar all the way to the left), previous steps' bricks' color are unchanged. With the factor at 100% (scroll bar all the way to the right), previous steps' bricks' color are the alternate color. With the factor at 50% (scroll bar in the middle), previous steps' bricks' are color that is a 50/50 mix of the bricks' color and the alternate color.
SUBMODELS
LPub supports different construction image background colors based on the sub-model level. The top level model is at level 0. A submodel used by the top level is 1. A submodel used by that submodel is level 2. The final level is level 3. A color can be associated with the background of construction images for each level. If a submodel's level is greater than 3, the color from level 3 is used.
LPub can create tiled images of small sub-assemblies that packs a set of steps into a single image. LPub calls these small images callouts.
You have control over the fonts used to annotate step numbers in the callouts, provided on the Submodel's tab.
PLI/BOM LPub can create a Bill of Materials (BOM) image that contains all the parts used to build the top level model, as well as BOM images for sub-models.
You decide the number of columns of parts in the Bill of Materials. The default is 5. You can change this to larger or smaller numbers.
The BOM image can get quite large, so LPub can scale the image size to a smaller more palatable size. You can constrain the BOM image's width, or the BOM image's height. In either case, the original aspect ratio of the BOM image is retained. If you want to modify the BOM's aspect ratio, change the number of columns.
CONTROLS
To create all your step images, LPub must create a lot of files. It creates DAT and POV files for each step in the assembly. By default LPub throws these files away once your images are generated. You can uncheck the Erase generated .DAT files to make LPub retain the generated DAT files. There is a similar check box for .POV files.
If you want to create all the generated DAT and POV files, but not run POV-Ray, uncheck the Run POV-Ray checkbox.
For large complex models, it is often easiest to manage the LDRAW files by breaking the design entry into modules. I like to make bipeds, so I often have the legs described each in separate file, and the body in a third file. I use a fourth file (often called complete.ldr) to pull all the parts together. It can take a long time to generate images for a complex design. If I've already generated the images for a given part, LPub will not regenerate the files unless I change the original LDRAW file. If I only change the design of one leg, I should only have to regenerate images for that leg, and the complete.ldr that uses it. This can save a lot of time.
If you want to force LPub to regenerate all the images anyway, uncheck the Run POV-RAY only if needed checkbox.
When you run LPub on LDRAW files you got off the internet, the designs may use parts that you do not have installed for LDRAW. LPub checks for this because it cannot complete processing of your images without knowing about all the part types used in the design. By default, LPub checks the entire design against the known parts when you open the design. If it finds parts missing, LPub will not process the file. You can turn off this check and run LPub at your own risk by unchecking the Check DAT(s) against Part List checkbox.
By default, LPub crops the generated images, because the first few step images have a few parts and a lot of background. You can override the default by unchecking the Crop Images checkbox.
LPub allows you to save your option configurations globally, which then become your personal defaults next time you bring up LPub. LPub also lets you save option configurations local to a specific directory. By default, when you open a file, LPub checks the current directory for a local configuration file, and if one exists it is opened and defaults are read. If you do not want to use local configuration files, uncheck the Auto load local configs checkbox.
L3P OPTIONS
The L3P options are broken down into 5 minor groups: Lights, Camera, Model, Surroundings, and Translate. These options only affect images rendered by Generate > Complete Assembly Image.
L3P LIGHTS OPTIONS
L3P has a rich and powerful set of lighting controls that you can configure using the Lights tab. LPub's default is to use L3P's default lighting. You can provide alternate lights by either creating an LDRAW file called lights.dat or by setting up to 32 lights using LPub.
If you create a lights.dat file, it must be in the same directory as your model. To use the light.dat as your lights, check the Use light.dat as light sources checkbox.
If you want to set your lighting configuration using LPub use the Custom Lights section of the L3P Lights tab. You can specify a light's location using globe coordinates or X,Y,Z coordinates. You can also specify a lights color using the Color button to the left of the light's coordinates.
You can configure multiple lights by setting up one light, changing the light number and setting up a second. The lights settings can be saved to a local configuration file using the File > Save Local Config menu in LPub's main window.
L3P has default settings for ambient light, diffuse light and reflections. LPub provides Ambient, Diffuse, and Reflection controls to override L3P's default value.
L3P CAMERA OPTIONS
You can access L3P's camera settings using the L3P Camera tab.
L3P lets you specify a camera angle, which controls the camera's field of view. A narrow angle acts like a telephoto lens on a camera. A wide angle lens acts like a macro lens. LPub's default camera angle is 67.5 degrees. This does not look that good for a sequence of assembly images, so LPub sets its default to 30 degrees. You can change the lens angle using the Lens Angle scroll bar. You can turn off LPub's use of lens angle by unchecking the Camera Angle check box.
If you want to eliminate perspective in your rendered images, you can check the Orthographic check box.
L3P lets you specify camera location and orientation using either globe coordinates or X,Y,Z coordinates. Globe coordinates use the familiar latitude and longitude used to describe a location on the earth's surface, where the camera is always looking at the origin of the scene. By default L3P places the camera at a latitude of 30 degrees, a longitude of 45 degrees and far enough away from your model so that the entire model is in the picture.
You can override the latitude/longitude settings by putting a check mark in the Globe Position check box, and setting the latitude and longitude fields. You can also force the distance between the camera and the origin using the Radius check box and the associated text field.
If X,Y,Z coordinates are preferred, you can check the XYZ check box, and fill in the X, Y and Z fields. By default L3P automatically points the camera. If you want to override L3P default pointing, you can check the Look At check box and fill in the X,Y, and Z fields provided.
L3P MODEL OPTIONS
The L3P Model tab lets you control attributes about the model itself. These options only affect images rendered using Generate > Complete Assembly Image.
To make it easier to see where one brick ends and the next one starts, L3P spreads the bricks out a bit by putting gaps between the seams. You can override L3P's default width between seam by checking the Seam Width check box, and providing a new seam with value.
In the virtual world of LEGO CAD, all instances of parts are exactly the same and have no imperfections. This makes for unrealistically perfect images. You can make your images look more realistic by adding small bumps to every surface of your design. You can turn on L3P's surface bumps by checking the Surface Bumps check box.
When rendering a DAT with a single part, L3P can make a mistake on its color. You can force the correct behavior using the Color check box, and the Color button that is next to it.
POV-Ray can take a long time to generate your pictures. The more detail in your model, the more time it takes to calculate and draw out. L3P lets you specify four levels of detail for your model. The Render Quality check box lets override the default detail of medium detail. The box to the right of the Render Quality check box, lets you chose the quality level.
L3P SURROUNDINGS OPTIONS
By default, L3P uses a black backdrop when creating your model. You can override this default using the Background Color check box. When you check the box, the color button will appear. Click the color button to change the color.
If you prefer, you can have L3P provide a floor by checking the Floor Enable check box. You can choose a grey floor or a red and white checked floor. The floor runs off to the horizon. By default, L3P sets the floor just below your model. You can override this by checking the Floor Altitude check box. You specify the height of the floor using the box that appears.
L3P TRANSLATE OPTIONS
The L3P Translate tab is kind of a miscellaneous tab for things that are specific to translating the model.
Luts Uhlmann has created a whole bunch of high quality LEGO parts for POV-Ray. He calls them LGEO. These parts are much higher precision than the normal parts. L3P provides support for using LGEO parts. To use LGEO parts, you must click the LGEO Browse button and it's open dialog to locate the LGEO parts directory on your computer (see Appendix A for LGEO installation instructions.) Once you've located the LGEO parts, you can check the LGEO Use check box to enable use of LGEO parts.
L3P provides its own drawing primitives when translating your model from LDRAW to POV format. You can force L3P to use the LDRAW primitives by checking the Don't substitute Primitives check box.
L3P has defined its own extensions to the LDRAW file format to make it easier to specify L3P behavior directly in a LDRAW file. The Exclude Non-POV Code prevents these extension from affecting the POV files output for POV-Ray.
L3P supports its own form of step image generation using POV-Ray a POV-Ray animation technique called step clocks. You can enable L3P's step clock behavior using the Enable Stepclock check box.
POV-RAY OPTIONS
Just below the POV tab, there is a list box that lets you choose amongst the various POV-Ray and MEGA-POV versions that are installed on your computer.
POV_Ray is an extremely powerful image rendering program. It has many features. Fortunately most of the features are related to describing the model in question, although it does have some command line options.
POV RENDERING OPTIONS
POV-Ray provides its own rendering quality controls, separate from those provided by L3P. LPub provides you with a list of all the quality levels. The ones at the top of the list are lowest quality, but fastest at drawing out your picture. The ones at the bottom of the list are the highest quality, but also take the longest to draw out your image.
POV-Ray provide a mechanism called anti-aliasing to make your pictures look smooth around the edges. By default POV-Ray does not use anti-aliasing. You can turn on anti-aliasing using the Anti-Aliasing Enable check box. POV-Ray provides two methods of anti-alias. Please see the POV-Ray documentation on anti-aliasing for details.
The Threshold, Depth and Jitter check boxes let you override the default depth, threshold and jitter used when you turn on anti-aliasing.
POV-RAY OUTPUT OPTIONS
The POV-Ray Output options let you configure specific attributes about POV-Ray output.
The Dimensions section lets you decide how big an image is generated (in pixels).
The File section lets you specify a specific file name for the resultant picture.
The Format section lets you choose between five output formats: Windows Bitmap, JPEG, Portable Network Graphics (PNG), Targa Uncompressed and Targa Compressed. POV-Ray does not actually support JPEG format, but LPub does and has POV-Ray generate Windows bitmap images, and then LPub converts them to JPEG when they are done. This format only affects images generated using the Generate > Complete Assembly menu.
By default, POV-Ray writes to your hard disk each time it finishes drawing a line. Disk speeds are very slow compared to internal computer speeds, so you may want to use POV-Ray's buffering mechanism to speed things up a bit. You can enable buffering using the Output Buffering check box. You provide the size of the buffer (in kilobytes) in the text box that becomes visible.
These options only affect Generate > Complete Assembly Image.
MEGA-POV OPTIONS
MEGA-POV is a modified version of POV-Ray that has a handy feature of edge detection. This feature can be used to outline each of the parts in your design. This makes it easier to identify individual bricks within a large design full of bricks.
This outlining mechanism has two parts: detecting edges that should be outline, and drawing in the outline. Edge detection is based on differences in depth, angle and color between neighboring pixels within a picture. The Edge Detection section provides fields that let you set these difference thresholds.
Once an edge is detected, the Line Format parameters Width, Sharpness and Color parameters define what the edge outlines look like. Please see MEGA-POV documentation on a description of how these controls work.
These options affect all MEGA-POV rendering.
LDGLITE RENDERER
Don Heyse modified the venerable LDLite to use a platform independent graphic library. He called it LDGLite. LDGLite is a very fast high-quality LDraw renderer. It has many advantages over POV-Ray, including incomparably faster rendering, edge line drawing, and automatic cropping of image so smallest dimensions.
At my request, Don also added L3P compatible -ca[angle] and -cg[latitude],[longitude],[radius] options to make LPub interfacing to ldGLite extremely easy.
Using ldGLite (and especially its automatic cropping), you can completely render a model's assembly and part list image in minutes instead of hours as it might take using POV-Ray.
ldGlite cannot provide the photo-realism provided by POV-Ray, but that capability is not needed to make instructions comparable to those made by LEGO.
LDVIEW RENDERER
Travis Cobbs wrote an LDraw renderer LDView. LDView is also a fast high-quality LDraw renderer. LDView also has advantages over POV-Ray, including faster rendering and edge line drawing.
At my request, Travis added L3P compatible -ca[angle] and -cg[latitude],[longitude],[radius] options to LDView.
LDView can provide high quality lighting and specular reflection, making images comparable to models rendered without shadows on POV-Ray, only at a much higher rendering rate.
LDView supports named preference sets. LPub has LDView render using the LPub preference set. Before you render using LDView, you should create an LPub preference set. The settings I recommend are:
General
Antialiasing: 16x
Antialiased line: Checked
Background Color: White
Geometry
Seam Width: Unchecked
BFC: Checked
Edge Lines: Checked
Conditional lines: Checked
High Quality: Checked
Thickness: all the way to the left.
Effects:
Lighting: Checked
High Quality: Unchecked
Specular Highlighting: Unchecked
Alternative setup: Unchecked
Transparency
Sort: Checked
Misc:
Smooth curves: Checked
Primitives:
Primitive substitution: Checked
Texture Studs: Checked
Trilinear filtering: selected
Misc:
Use hi-res primitives when available
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 Extras 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, base plates 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
LPub maintains a part image database for each model you process. LPub creates an LPub\Parts subdirectory in the current working directory that contains the model being processed. LPub tracks the render settings used to create the part images. If you change the rendering settings, LPub erases the cache of previously generated images, and rerenders any images needed.
Meta-Commands
LPub support meta-commands defined by LDraw, MLCAD, LSynth and LPub itself. LPub supports these LDraw meta-commands:
CLEAR STEPLPub supports these MLCAD meta-commands:
ROTSTEP BUFEXCHG GHOST GROUPLPub supports LSynth, a bendable part synthesizer for tubes and rubber bands. LSynth provides this meta-command:
SYNTHLPub defines some extensions to the LDraw command set in the form of meta-commands. LPub defines these meta-commands for its use:
BI BEGIN GREYED - using buffer exchange to create "exploded" building
instructions, combined with LPub's feature to grey out parts from
previous steps, can produce confusing greying behaviors. Parts that
exploded from the main design in one step, and then compacted into
the design into the next step using buffer exchange, can come up
non-greyed. You can force graying on a list of parts by preceding
the parts with BI BEGIN GREYED and BI END.
LPUB GROUP REMOVE - The original LDraw file format does not
provide a way of moving, turning, or modifying parts during the
display of CSIs. The original LDraw file format does allow the
removal of the entire model using the CLEAR command. MLCad advanced
modification of the model by introducing the BUFEXCHG, which lets
you remember the model as of a particular step, and restore it later,
effectively removing the parts added between saving and restoring.
LPub advances modification of the model even further by introducing
the LPUB REMOVE GROUP meta-command. Removing groups only works for
previously defined groups within the same file. Groups with blanks
in their name must be enclosed in double quotes.
LPUB INCLUDE filename
This provides a way of specifying LPUB layout properties in a file
without that file being percieved as a sub-model.
LAYOUT
LPub provides a mechanism for merging your assembly images and part list images into building instruction pages. This process is called layout. LPub provides you with many meta-commands that let you control layout.
When placing various components of your page, you place them relative to something. You can specify absolute placement by placing things relative to the PAGE, or you can specify things relatively, by placing things relative to something within the page (e.g. ASSEM or PLI).
LPub lets you place the following things relative to the PAGE: ASSEM, PLI, CALLOUT and STEP_NUMBER.
LPub lets you place things relative to the assembly picture (ASSEM): STEP_NUMBER and CALLOUT. LPub lets you place things relative to the PLI: STEP_NUMBER.
When placing things relative to the PAGE, you can only place things inside the PAGE, otherwise your thing would be rendered off page, and therefore invisible. When placing things relative to the PLI, you can only place things outside the PLI, otherwise you will be drawing things over the top of the PLI. When placing things relative to the assembly image, you can place them either inside or outside the rectangle that contains the image.
Below is a diagram that shows you the terms used when placing things relative to something else. The diagram shows a rectangle with words that describe locations both inside and outside the rectangle.
Inside the a rectangle you have eight choices, the four corners, or the four edges. For edges, it is implied that things are placed relative to the center of the edge.
LPub provides 16 locations relative to the outside of the rectangle. There are the four corners, and four edges, just like within the rectangle. LPub provides a bit more control for the edges. This control justification. For TOP and BOTTOM edges, LPub provides LEFT, CENTER and RIGHT justification. For LEFT and RIGHT justification, LPub provides TOP, CENTER and BOTTOM justification.
Here is an explicit list of the possible placements relative to a rectangle.
TOP_LEFT | TOP/LEFT TOP/CENTER TOP/RIGHT | TOP_RIGHT
---------------------------------------------------------------
LEFT/TOP | TOP_LEFT TOP TOP_RIGHT | RIGHT/TOP
LEFT/CENTER | LEFT /* Inside */ RIGHT | RIGHT/CENTER
LEFT/BOTTOM | BOTTOM_LEFT BOTTOM BOTTOM_RIGHT | RIGHT/BOTTOM
---------------------------------------------------------------
BOTTOM_LEFT | BOTTOM/LEFT BOTTOM/CENTER BOTTOM/RIGHT | BOTTOM_RIGHT
PAGE LAYOUT PROPERTIES
LPub lets you define the dimensions, margins and background image used for each building instruction page. Typically you'd set these properties in the top level model file.
LPUB PAGE SIZE width height
- width and height are in pixels.
LPUB PAGE PLI (YES|NO)
- NO specifies you don't want PLI images generated or used in layout.
The default is yes.
LPUB PAGE BACKGROUND TRANS
- makes the background of each page be transparent
LPUB PAGE BACKGROUND color
- color can be in decimal or hexadecimal (use 0x prefix)
LPUB PAGE BACKGROUND [STRETCH] png_image_name
- png_image_name is an image in Portable Network Graphics (PNG) format.
if png_image_name is larger than the page, png_image_name is
cropped to page size. If png_image_name is smaller than the page and
STRETCH is specified, png_image_name is stretched to meet the page
dimensions. If png_image_name is smaller than the page and STRETCH is
not specified, png_image_name is tiled vertically and horizontally to
fill the page.
LPUB PAGE BORDER SQUARE color thickness
- when specified a square border of color and thickness is drawn
around the page. thickness is specified in pixels.
LPUB PAGE BORDER ROUND color thickness corner_radius
- when specified a color border with rounded corners of radius
corner_radius (in pixels) is drawn around the page. thickness
controls how wide the border is (in pixels).
LPUB PAGE BORDERLESS
LPUB PAGE BORDER MARGINS x_margin y_margin
- ASSEM, PLI, and CALLOUT placed in the page are offset x_margin and y_margin
off the edges of the page. x_margin and y_margin are in pixels.
LPUB PAGE NUMBER MARGINS x_margin y_margin
- the page number is always located in the bottom right hand corner of the
page. x_margin is the number of pixels that separates the page
number from the right edge of the page. y_margin is the number of
pixels the page number is separates the page number from the bottom of the
page. PAGE NUMBER placement is not affected by PAGE BORDER MARGINS.
LPUB PAGE INSERT pngimage_name left top
- the file pngimage_name is added to the current page and placed at page
width times left and page height times top
ASSEM LAYOUT PROPERTIES
Assem layout meta-commands control the placement of assembly step images (CSIs) relative to the INSIDE of PAGE.
LPUB ASSEM MARGINS x_margin y_margin
- all things placed relative to ASSEM OUTSIDE are spaced x_margin and y_margin.
x_margin and y_margin are in pixels.
LPUB ASSEM PLACEMENT corner PAGE
- corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, BOTTOM_RIGHT or CENTER.
LPUB ASSEM PLACEMENT edge justification PAGE
- edge can be TOP, or BOTTOM.
- justification can be LEFT, CENTER or RIGHT.
LPUB ASSEM PLACEMENT edge justification PAGE
- edge can be LEFT, or RIGHT.
- justification can be TOP, CENTER or BOTTOM.
LPUB ASSEM PLACEMENT CENTER PAGE
- places the assembly image in the center of the page.
LPUB ASSEM PLACEMENT OFFSET x_offset y_offset
- x_offset and y_offset are relative to the placement on the page.
x_offset is a value from -1 to 1, and is multiplied by the page width
to calculate a pixel offset. y_offset is a value from -1 to 1, and is
multiplied by the page height to calculate a pixel offset.
MULTI_STEP LAYOUT ACTIONS
MULTI_STEP lets you create a single page with many assembly steps arranged in rows or columns. It provides a great way of compacting the information in your building instructions.
LPUB MULTI_STEP BEGIN
- this should be placed before any parts are added after the most recent step.
It indicates that two or more steps will be displayed on a given page.
LPUB RESERVE factor
- this reserves some space within the current row or column. The amount of
space is calculated by factor by one of the two page dimensions. For
example it can be used to reserve some space in the first column by
multiplying factor by page height.
LPUB MULTI_STEP DIVIDER
- This indicates that you want to stop appending steps to the current row or
column, and start on a new row or column
LPUB MULTI_STEP END
- This indicates that you are done adding steps to the current page.
MULTI_STEP LAYOUT PROPERTIES
These properties are used by LPub to compose your MULTI_STEP page.
LPUB MULTI_STEP HORIZONTAL
- forces the steps in a callout to be packed horizontally
LPUB MULTI_STEP HORIZONTAL
- forces the steps in a callout to be packed vertically
LPUB MULTI_STEP SEPARATOR thickness color
- thickness tells how thick (in pixles) the rendered divider will be.
Zero means no divider. color defines the color used when drawing the
divider. color is in RGB values, not LDraw color numbers.
LPUB MULTI_STEP MARGINS x_margin y_margin
- x_margin and y_margin are in pixels.
LPUB MULTI_STEP PLI PER_STEP (TRUE|FALSE)
- This enables each step in a MULTI_STEP page to have its own PLI. The default
is FALSE, which means the page will have one part list image that contains
all the parts added in each step within the page. PLI PER_STEP TRUE is
a very effective way of communicating the parts used in each step.
LPUB MULTI_STEP PLI PLACEMENT edge justification ASSEM preposition
- When PLI PER_STEP is TRUE, this meta-command can be used to control the
placement of the PLI within the MULTI_STEP page. edge can be either
TOP or BOTTOM, justification can be LEFT, CENTER, or RIGHT, and
preposition can be either INSIDE or OUTSIDE.
LPUB MULTI_STEP PLI PLACEMENT edge justification ASSEM preposition
- When PLI PER_STEP is TRUE, this meta-command can be used to control the
placement of the PLI within the MULTI_STEP page. edge can be either
LEFT or RIGHT, justification can be TOP, CENTER, or BOTTOM, and
preposition can be either INSIDE or OUTSIDE.
LPUB MULTI_STEP PLI PLACEMENT corner ASSEM (INSIDE|OUTSIDE)
- Corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_RIGHT, or BOTTOM_LEFT.
LPUB MULTI_STEP PLI PLACEMENT OFFSET x_factor y_factor
- x_factor and y_factor are multiplied by the size of the
assembly image and are added to the x and y placement values calculated
using the PLI PLACEMENT meta-commands above.
LPUB MULTI_STEP PLI PLACEMENT MARGINS x_margin, y_margin
- x_margin defines a buffer around the outside of the PLI where nothing
can be placed.
LPUB MULTI_STEP STEP_NUMBER PLACEMENT edge justification ASSEM (INSIDE|OUTSIDE)
- edge can be either TOP or BOTTOM, justification can be
LEFT, CENTER, or RIGHT, and preposition can be either INSIDE or OUTSIDE.
LPUB MULTI_STEP STEP_NUMBER PLACEMENT edge justification ASSEM (INSIDE|OUTSIDE)
- edge can be either LEFT or RIGHT, justification can be
TOP, CENTER, or BOTTOM, and preposition can be either INSIDE or OUTSIDE.
LPUB MULTI_STEP STEP_NUMBER PLACEMENT corner ASSEM (INSIDE|OUTSIDE)
- Corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_RIGHT, or BOTTOM_LEFT.
LPUB MULTI_STEP STEP_NUMBER PLACEMENT OFFSET x_factor y_factor
- x_factor and y_factor are multiplied by the size of the
assembly image and are added to the x and y placement values calculated
using the STEP_NUMBER PLACEMENT meta-commands above.
CALLOUT LAYOUTS
Callout images are composite images of a submodel with a small number of steps. The steps in a callout image can be gathered into rows or columns. Each step within a callout has its own step number. You decide how many steps are in each row or column by providing divider statements. Rows and columns are visually separated by horizontal or vertical lines.
The contents of the PLI for a given step are affected by the use of callouts. Without callout, the parts added in a submodel are not added to the parts specified in a step that adds a submodel. With callout, the parts added in a called out submodel, are added to the PLI for the current step.
LPub has no method for defining the overall size of the composite callout image. The size of the image depends on the size of the step images from the submodel, the margins, the step number, the dividers, and how the steps are divided.
This LEGO page contains a large callout image with many parts. Notice all the parts show up in the PLI for the page.
LPub supports nested callouts as can be seen in this LEGO page.
LPub supports multiple callouts per step as can be seen in this LEGO page. This page also use the same callout submodel twice in the same page. LPub supports a callout being used up to 16 times within the same page.
CALLOUT LAYOUT ACTIONS
LPUB CALLOUT BEGIN
LPUB CALLOUT END
- typically placed around a single sub-model usage, and a callout image is
generated from the step images for that sub-model. Multiple sub-model
usages with one pair of BEGIN/END is currently not supported.
LPUB CALLOUT DIVIDER
- Use this meta-command in files that are called out, to tell LPub where you want
dividers in your callout. Place a divider between any two steps. The step
following the divider will be at the beginning of row (for horizontal placement) or
top of column (for vertical placement)
CALLOUT LAYOUT PROPERTIES
These properties are used to calculate the final format of your callouts.
LPUB CALLOUT MARGINS x y
- these margins specify the distance between ASSEM (plus their
step number) and adjacent ASSEMs (plus their step number) within
the callout. These margins are in pixels. In callouts, ASSEM
margins define the distance between ASSEMs and their associated
step numbers.
LPUB CALLOUT HORIZONTAL
- forces the steps in a callout to be packed horizontally
LPUB CALLOUT VERTICAL
- forces the steps in a callout to be packed vertically
LPUB CALLOUT SEPARATOR seperator_color separator_width
separator_width defines the width (in pixels) of a line between two
row margins. separator_width of 0 means no line.
LPUB CALLOUT BORDER SQUARE color thickness
- this draws a rectangle around your callout image that has square corners.
color is an RGB value (in hex or decimal) that is the color of the outline.
thickness is the thickness of the drawn outline (in pixels)
LPUB CALLOUT BORDER ROUND color thickness radius
- this draws a rectangle with rounded corners around your callout image.
color is an RGB color value for the color of the border.
thickness is the thickness of the outline (in pixels)
radius is the radius of the corner (in pixels). Small radius give
sharper corners. A larger radius gives you more rounded corners.
LPUB CALLOUT BORDER MARGINS x y
- these margins define the distance between the ASSEMs (plus their step
numbers), and the edges of PLI.
LPUB CALLOUT BORDERLESS
- this draws no border around the callout.
LPUB CALLOUT BACKGROUND TRANS
- this makes the background of the callout image transparent.
LPUB CALLOUT BACKGROUND color
- color can be in decimal or hexadecimal (indicated by a prefix of 0x)
LPUB CALLOUT BACKGROUND [STRETCH] fname
- lpub uses the PNG image found in file fname. If the background image is larger
than the callout image, the background image is cropped. If the background image
is smaller than the callout image and STRETCH is indicated, the background image
is stretched to match the dimensions of the callout image. If the background
image is smaller than the callout image and STRETCH is not indicated, the background
image is tiled repeatedly horizontally and vertically to fill the callout with
background images.
LPUB CALLOUT INSTANCE_COUNT MARGINS x y
- If you have a step that uses a given sub-model more than once, you can enclose
the multiple usages inside a CALLOUT BEGIN/END. LPub will count the numbeer of
times you use the sub-model, and render this instance count within your callout
image. These margins define the distance between the rectangle that encloses
the the callled out steps and the rendered instance count.
These meta-commands let you place the instance_count relative to the rectangle that
encloses the called out steps.
LPUB CALLOUT INSTANCE_COUNT PLACEMENT corner CALLOUT preposition
- you can control the placement of the instance_count relative to the rectangle
that encloses the called out steps. corner can be one of TOP_LEFT, TOP_RIGHT,
BOTTOM_LEFT or BOTTOM_RIGHT. preposition can be either INSIDE or OUTSIDE.
LPUB CALLOUT INSTANCE_COUNT PLACEMENT edge CALLOUT INSIDE
- edge can be TOP, BOTTOM, RIGHT or LEFT. The instance_count will be rendered
on the center of the specified edge.
LPUB CALLOUT INSTANCE_COUNT PLACEMENT horiz justification CALLOUT OUTSIDE
- horiz can be either TOP or BOTTOM. Justification can be LEFT, CENTER or
RIGHT.
LPUB CALLOUT INSTANCE_COUNT PLACEMENT vert justification CALLOUT OUTSIDE
- vert can be either LEFT or RIGHT. Justification can be TOP, CENTER or
BOTTOM.
These meta-commands let you place callout images. They can be placed on the inside
of PAGE, or the INSIDE or OUTSIDE of an ASSEM.
LPUB CALLOUT PLACEMENT CENTER PAGE
- the CALLOUT is placed in the center of the PAGE.
LPUB CALLOUT PLACEMENT corner PAGE
- the CALLOUT is placed in the corner of the PAGE. corner can
be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, or BOTTOM_RIGHT. The CALLOUT is
offset from the corner of the page by PAGE BORDER MARGINS.
LPUB CALLOUT PLACEMENT edge PAGE
- the CALLOUT is placed in the center of the edge of the PAGE. edge
can be TOP, BOTTOM, LEFT or RIGHT. The CALLOUT is offset from the edge
of the page by PAGE BORDER MARGINS.
LPUB CALLOUT PLACEMENT CENTER ASSEM INSIDE
- the CALLOUT is placed in the center of the ASSEM image. ASSEM MARGINS
do not affect INSIDE PLACEMENT.
LPUB CALLOUT PLACEMENT corner ASSEM INSIDE
- the CALLOUT is placed in the inside corner of the ASSEM image.
corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, or BOTTOM_RIGHT.
ASSEM MARGINS do not affect INSIDE PLACEMENT.
LPUB CALLOUT PLACEMENT edge ASSEM INSIDE
- the CALLOUT is placed in the center of the edge of the ASSEM image.
edge can be TOP, BOTTOM, RIGHT or LEFT. ASSEM MARGINS do not
affect INSIDE PLACEMENT.
LPUB CALLOUT PLACEMENT corner ASSEM OUTSIDE
- the CALLOUT is placed in the outside corner of the ASSEM image.
corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, or BOTTOM_RIGHT.
The CALLOUT is offset from the corner of the ASSEM by ASSEM MARGINS.
LPUB CALLOUT PLACEMENT edge justification ASSEM OUTSIDE
- the CALLOUT is placed in the center of the edge of the ASSEM image.
edge can be TOP, BOTTOM, RIGHT or LEFT. TOP or BOTTOM edge
can have justification of LEFT, CENTER or RIGHT. RIGHT or LEFT edge
can have justification of TOP, CENTER or BOTTOM. The CALLOUT is
offset from the ASSEM by ASSEM MARGINS.
LPUB CALLOUT PLACEMENT OFFSET x_offset y_offset
- x_offset and y_offset are typically in the range of -1 to 1.
x_offset is multiplied by PAGE or ASSEM width to calculate a horizontal
pixel displacement. y_offset is multiplied by PAGE or ASSEM height
to calculate a vertical pixel displacement.
LPUB CALLOUT POINTER BASE base
- callout pointers are triangles that point from the callout picture to somewhere
in the step image to show where the assembly from the callout is used in the step.
One edge of the triangle overlaps the callout, and the other two edges of the
triangle converge to point somewhere in the step image. The overlapping edge of the
triangle is twice base's value (in pixels).
LPUB CALLOUT POINTER placement loc assem_x assem_y
- the allows you to create triangle pointers from a given callout to
the assem_x/assem_y location within the assembly image.
loc specifies where the triangle overlaps into the callout image.
For placement of TOP and BOTTOM, is a scalar that is multiplied by
the callout's width (typically a value from 0 to 1) to convert it to pixels.
For placement of RIGHT and LEFT, is a scalar that is multiplied by the
callout's height to convert it to pixels. For callout placements in the
corners of a step image is not used.
You can have up to 16 pointers per callout.
LPUB CALLOUT PLI PER_STEP (TRUE|FALSE)
- This enables each step in a CALLOUT page to have its own PLI. The default
is FALSE, which means the page will have one part list image that contains
all the parts added in each step within the page. PLI PER_STEP TRUE is
a very effective way of communicating the parts used in each step.
LPUB CALLOUT PLI PLACEMENT edge justification ASSEM preposition
- When PLI PER_STEP is TRUE, this meta-command can be used to control the
placement of the PLI within the CALLOUT step. edge can be either
TOP or BOTTOM, justification can be LEFT, CENTER, or RIGHT, and
preposition can be either INSIDE or OUTSIDE.
LPUB CALLOUT PLI PLACEMENT edge justification ASSEM preposition
- When PLI PER_STEP is TRUE, this meta-command can be used to control the
placement of the PLI within the CALLOUT step. edge can be either
LEFT or RIGHT, justification can be TOP, CENTER, or BOTTOM, and
preposition can be either INSIDE or OUTSIDE.
LPUB CALLOUT PLI PLACEMENT corner ASSEM (INSIDE|OUTSIDE)
- Corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_RIGHT, or BOTTOM_LEFT.
LPUB CALLOUT PLI PLACEMENT OFFSET x_factor y_factor
- x_factor and y_factor are multiplied by the size of the
assembly image and are added to the x and y placement values calculated
using the PLI PLACEMENT meta-commands above.
LPUB CALLOUT PLI PLACEMENT MARGINS x_margin, y_margin
- x_margin defines a buffer around the outside of the PLI where nothing
can be placed.
LPUB CALLOUT STEP_NUMBER PLACEMENT edge justification ASSEM (INSIDE|OUTSIDE)
- edge can be either TOP or BOTTOM, justification can be
LEFT, CENTER, or RIGHT, and preposition can be either INSIDE or OUTSIDE.
LPUB CALLOUT STEP_NUMBER PLACEMENT edge justification ASSEM (INSIDE|OUTSIDE)
- edge can be either LEFT or RIGHT, justification can be
TOP, CENTER, or BOTTOM, and preposition can be either INSIDE or OUTSIDE.
LPUB CALLOUT STEP_NUMBER PLACEMENT corner ASSEM (INSIDE|OUTSIDE)
- Corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_RIGHT, or BOTTOM_LEFT.
LPUB CALLOUT STEP_NUMBER PLACEMENT OFFSET x_factor y_factor
- x_factor and y_factor are multiplied by the size of the
assembly image and are added to the x and y placement values calculated
using the STEP_NUMBER PLACEMENT meta-commands above.
PLI LAYOUT ACTIONS
These meta-statements affect the contents of PLIs and BOMs.
LPUB PLI BEGIN IGN
- when combined with LPUB PLI END, provides a way for you to have LPUB
ignore parts in your LDraw file. This is typically used for parts that
are added between a BUFFER_EXCHG STORE and BUFFER_EXCHG RETRIEVE.
LPUB PLI BEGIN SUB part
- when combined with LPUB PLI END provides a way for you to substitute
one or more parts within your model with the part. This
is typically used when using some parts to create a composite part.
For example, the NXT motor comes in a complete form, as well as a
partially complete motor with with the motor shaft separately. You
might do this if you need the motor drive wheel at a different rotation
than the fully complete motor. part can be either a user defined
part or a part from the PARTS or P directory.
LPUB PLI BEGIN SUB color part
- when combined with LPUB PLI END provides a way to substitute one or
more parts within your model with the part. color lets
you control the color of the rendered part. color is an LDraw
color.
LPUB PLI END
- ends a PLI IGN or SUB
PLI LAYOUT PROPERTIES
PLI layout meta-commands control the dimensions, look and placement of the PLIs in the page. PLI can be placed relative to INSIDE of PAGE, and INSIDE or OUTSIDE of ASSEM. These placements are only used outside of callouts and in single step pages.
LPUB PLI PART MARGINS x y
- these margins (in pixels) define the distance between the edge of the
part, and the instance count, and annotation string.
LPUB PLI MARGINS x y
- these margins (in pixels) define the distance between the combination
of the part, instance count, and possibly annotation string and the
neighboring part, instance_count, and possibly annotation string.
LPUB PLI PLACEMENT CENTER PAGE
- the PLI is placed in the center of the PAGE.
LPUB PLI PLACEMENT corner PAGE
- the PLI is placed in the corner of the PAGE (offset by PAGE
BORDER MARGINS). corner can be TOP_LEFT, TOP_RIGHT,
BOTTOM_LEFT, or BOTTOM_RIGHT.
LPUB PLI PLACEMENT edge PAGE
- the PLI is placed in the center of the edge of the PAGE.
edge can be TOP, BOTTOM, LEFT or RIGHT.
LPUB PLI PLACEMENT CENTER ASSEM INSIDE
- the PLI is placed in the center of the ASSEM image.
LPUB PLI PLACEMENT corner ASSEM INSIDE
- the PLI is placed in the inside corner of the ASSEM image.
corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, or BOTTOM_RIGHT.
LPUB PLI PLACEMENT edge ASSEM INSIDE
- the PLI is placed in the center of the edge of the ASSEM image.
edge can be TOP, BOTTOM, RIGHT or LEFT.
LPUB PLI PLACEMENT corner ASSEM OUTSIDE
- the PLI is placed in the outside corner of the ASSEM image
(offset by ASSEM MARGINS). corner can be TOP_LEFT, TOP_RIGHT,
BOTTOM_LEFT, or BOTTOM_RIGHT.
LPUB PLI PLACEMENT edge justification ASSEM OUTSIDE
- the PLI is placed in the center of the edge of the ASSEM image.
edge can be TOP, BOTTOM, RIGHT or LEFT. TOP or BOTTOM
edge can have justification of LEFT, CENTER or RIGHT.
RIGHT or LEFT edge can have justification of TOP,
CENTER or BOTTOM. The thing being places is offset from the edges
by ASSEM MARGINS.
LPUB PLI PLACEMENT OFFSET x_offset y_offset
- x_offset and y_offset are typically in the range of -1 to 1.
x_offset is multiplied by PAGE or ASSEM width to calculate a horizontal
pixel displacement. y_offset is multiplied by PAGE or ASSEM height
to calculate a vertical pixel displacement.
LPUB PLI BORDER SQUARE color thickness
- this draws a rectangle around your PLI image that has square corners.
color is an RGB value (in hex or decimal) that is the color of the outline.
thickness is the thickness of the drawn outline (in pixels.)
LPUB PLI BORDER ROUND color thickness radius
- this draws a rectangle with rounded corners around your PLI image.
color is an RGB color value for the color of the border.
thickness is the thickness of the outline (in pixels)
radius is the radius of the corner (in pixels). Small radius give
sharper corners. A larger radius gives you more rounded corners.
LPUB PLI BORDERLESS
- this draws no border around the PLI.
LPUB PLI BORDER MARGINS x y
- these margins define the spacing between parts (and their text) and the
border of the PLI.
LPUB PLI BACKGROUND TRANS
- this makes the background of the PLI image transparent.
LPUB PLI BACKGROUND color
- color can be in decimal or hexadecimal (indicated by a prefix of 0x)
LPUB PLI BACKGROUND [STRETCH] fname
- lpub uses the PNG image found in file fname as a the background image. If the
background image is larger than the PLI image, the background image is cropped.
If the background image is smaller than the PLI image and STRETCH is indicated,
the background image is stretched to match the dimensions of the PLI image. If
the background image is smaller than the PLI image and STRETCH is not indicated,
the background image is tiled repeatedly horizontally and vertically to fill the
PLI with background images.
LPUB PLI CONSTRAIN AREA
- this makes LPub pick the dimensions of the PLI such that the PLI takes the
smallest possible area.
LPUB PLI CONSTRAIN SQUARE
- this makes LPub pick the dimensions of the PLI that are closest to square.
LPUB PLI CONSTRAIN WIDTH width
- this makes LPub constrain the width of the PLI, while stacking the columns
within the PLI to approximately the same height.
LPUB PLI CONSTRAIN HEIGHT height
- this makes LPub constrain the height of the PLI, producing as many columns
of parts as needed.
LPUB PLI CONSTRAIN COLS cols
- this makes LPub use only cols columns in the PLI, while stacking the
columns as evenly as possible.
STEP NUMBER LAYOUT PROPERTIES
Finally we need a way to control the placement of the step number for the step within a single step page, steps within the multi_step page, or steps within a callout. You can change STEP_NUMBER placement and margins on each step. Dilligent use of STEP_NUMBER placement can reduce the area taken up by steps, multiple steps and calllouts.
STEP_NUMBER placement and margins specified inside CALLOUT BEGIN/END, only apply to the callout. After the CALLOUT END, the palcement and margins are restored to their value from before the the CALLOUT BEGIN.
In single step pages, STEP_NUMBER can be placed relative to INSIDE of the PAGE, OUTSIDE of the PLI, and INSIDE or OUTSIDE of ASSEM. In multi_step and callouts, STEP_NUMBER can only be placed INSIDE or OUTSIDE of ASSEM.
LPUB STEP_NUMBER PLACEMENT CENTER PAGE
- the STEP_NUMBER is placed in the center of the PAGE.
LPUB STEP_NUMBER PLACEMENT corner PAGE
- the STEP_NUMBER is placed in the corner of the PAGE.
corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, or
BOTTOM_RIGHT. The STEP_NUMBER is offset from the corner
of PAGE by PAGE BORDER MARGINS.
LPUB STEP_NUMBER PLACEMENT edge PAGE
- the STEP_NUMBER is placed in the center of the edge
of the PAGE. edge can be TOP, BOTTOM, LEFT or RIGHT.
The STEP_NUMBER is offset from the corner of PAGE by PAGE
BORDER MARGINS.
LPUB STEP_NUMBER PLACEMENT CENTER ASSEM INSIDE
- the STEP_NUMBER is placed in the center of the ASSEM image.
LPUB STEP_NUMBER PLACEMENT corner ASSEM INSIDE
- the STEP_NUMBER is placed in the inside corner of the ASSEM image.
corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, or BOTTOM_RIGHT.
ASSEM MARGINS do not apply for ASSEM INSIDE PLACEMENT.
LPUB STEP_NUMBER PLACEMENT edge ASSEM INSIDE
- the STEP_NUMBER is placed in the center of the edge of the ASSEM image.
edge can be TOP, BOTTOM, RIGHT or LEFT.
ASSEM MARGINS do not apply for ASSEM INSIDE PLACEMENT.
LPUB STEP_NUMBER PLACEMENT corner PLI
- the STEP_NUMBER is placed in the outside corner of the PLI image.
corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, or BOTTOM_RIGHT.
The STEP_NUMBER is offset from the outside corner of the PLI by
PLI BORDER MARGINS.
LPUB STEP_NUMBER PLACEMENT edge justification PLI
- the STEP_NUMBER is placed in the center of the edge of the PLI image.
edge can be TOP, BOTTOM, RIGHT or LEFT. TOP or BOTTOM edge
can have justification of LEFT, CENTER or RIGHT. RIGHT or LEFT edge
can have justification of TOP, CENTER or BOTTOM.
The STEP_NUMBER is offset from the outside corner of the PLI by
PLI BORDER MARGINS.
LPUB STEP_NUMBER PLACEMENT corner ASSEM OUTSIDE
- the STEP_NUMBER is placed in the outside corner of the ASSEM image.
corner can be TOP_LEFT, TOP_RIGHT, BOTTOM_LEFT, or BOTTOM_RIGHT.
The STEP_NUMBER is offset from the outside corner of the ASSEM by
ASSEM MARGINS.
LPUB STEP_NUMBER PLACEMENT edge justification ASSEM OUTSIDE
- the STEP_NUMBER is placed in the center of the edge of the ASSEM image.
edge can be TOP, BOTTOM, RIGHT or LEFT. TOP or BOTTOM edge
can have justification of LEFT, CENTER or RIGHT. RIGHT or LEFT edge
can have justification of TOP, CENTER or BOTTOM.
The STEP_NUMBER is offset from the edge of the ASSEM by
ASSEM MARGINS.
The above attributes can be used globally or locally. If you specify LPub attribute meta-commands outside of CALLOUT BEGIN/END statements, those attributes apply to the rest of the model within the file, and for any sub-models referenced within the file. These attributes are considered global to the file.
If you specify LPub attribute meta-commands inside of CALLOUT BEGIN/END, those attributes only apply until the CALLOUT END, and for any called out sub-models.
BILL OF MATERIALS LAYOUT PROPERTIES
LPUB BOM PART MARGINS x y
- these margins (in pixels) define the distance between the edge of the
part, and the instance count, and annotation string.
LPUB BOM MARGINS x y
- these margins (in pixels) define the distance between the combination
of the part, instance count, and possibly annotation string and the
neighboring part, instance_count, and possibly annotation string.
LPUB BOM BEGIN IGN
- this is used in alternate models of a given set, to prevent the parts used in
the alternate models from showing up multiple times in the Bill of Materials.
Parts added after the LPUB BOM BEGIN IGN up until the LPUB BOM END, will not
be tallied in the part counts for Bill of Materials
LPUB BOM END
LPUB BOM BORDER SQUARE color thickness
- this draws a rectangle around your PLI image that has square corners.
color is an RGB value (in hex or decimal) that is the color of the outline.
thickness is the thickness of the drawn outline (in pixels.)
LPUB BOM BORDER ROUND color thickness radius
- this draws a rectangle with rounded corners around your PLI image.
color is an RGB color value for the color of the border.
thickness is the thickness of the outline (in pixels)
radius is the radius of the corner (in pixels). Small radius give
sharper corners. A larger radius gives you more rounded corners.
LPUB BOM BORDERLESS
- this draws no border around the BOM.
LPUB BOM BORDER MARGINS x y
- these pargins define the distance between the parts (plus their instance
count, and possibly annotate string), and the edge of the BOM image.
LPUB BOM BACKGROUND TRANS
- this makes the background of the PLI image transparent.
LPUB BOM BACKGROUND color
- color can be in decimal or hexadecimal (indicated by a prefix of 0x)
LPUB BOM BACKGROUND [STRETCH] fname
- lpub uses the PNG image found in file fname as a the background image. If the
background image is larger than the PLI image, the background image is cropped.
If the background image is smaller than the PLI image and STRETCH is indicated,
the background image is stretched to match the dimensions of the PLI image. If
the background image is smaller than the PLI image and STRETCH is not indicated,
the background image is tiled repeatedly horizontally and vertically to fill the
PLI with background images.
LPUB BOM CONSTRAIN AREA
- this makes LPub pick the dimensions of the PLI such that the PLI takes the
smallest possible area.
LPUB BOM CONSTRAIN SQUARE
- this makes LPub pick the dimensions of the PLI that are closest to square.
LPUB BOM CONSTRAIN WIDTH width
- this makes LPub constrain the width of the PLI, while stacking the columns
within the PLI to approximately the same height.
LPUB BOM CONSTRAIN HEIGHT height
- this makes LPub constrain the height of the PLI, producing as many columns
of parts as needed.
LPUB BOM CONSTRAIN COLS cols
- this makes LPub use only cols columns in the PLI, while stacking the
columns as evenly as possible.
LPUB BOM SORT WIDTH
- In BOMs, by default, LPub sorts color/parts by their LDRaw classification
(e.g. PLATE, BRICK, TECHNIC) and then their width. This makes the BOM
orderly, but not packed very densly. This meta-command makes LPub sort the
parts only by their width (ignoring classification), allowing for better
packing density.
LPUB BOM PACK SUBS
- In PLIs, LPub packs parts into columns, then rows, then sub-collumns and
sub-rows. This allows for dense PLI packing. For BOMs, the default is to
not allow sub-rows or sub-columns. This meta-command allows LPub pack
BOMs using sub-collumns, and sub-rows.
GENERATED IMAGE FILE NAMES
When creating building instructions, LPub creates at least two images for each
step in a given DAT file. The file name for the construction image depends on
the DAT name, the step number within the DAT (STEP or ROTSTEP), and the submodel
level. The format for the construction file name is The name for the part image for a given step is The name for a given callout image created for a step is based on the name
of the DAT file that specifies the callout: BLACK AND WHITE IMAGES
When producing print resolution documentation, you have the option to make
LPub operate in black and white mode. When LPub produces the images in black
and white, it is hard for the reader to tell what color the parts should be.
LPub puts color labels on the parts in the part list images so the reader can
tell what color part to use. Here is a list of the color labels and their meaning.
APPENDIX A - INSTALLING LPUB
LPub requires three external programs to complete its job: LDRAW/MLCAD the
CAD programs, 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. You can install LDRAW
anywhere you want. The first time you use LPub it will ask you to locate the
LDRAW directory. After that LPub will remember where you installed LDRAW.
To acquire L3P, use this link:
When the L3P zip file is downloaded, extract L3P.EXE to anywhere you want.
The first time you run LPub, it will ask you to locate L3P. Once located, LPub
remembers where you installed L3P.
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 will look up POV-Ray installation information in
the Windows Registry.
To acquire MEGA-POV, use this link:
and follow the installation instructions provided. MEGA-POV works with version
3.1 of POV-Ray and needs to be extracted into the same directory as POV-Ray's
pvengine.exe (hint To acquire LGEO parts library use this link:
You can extract the LGEO files to any directory you wish. LPub will ask you
to locate the LGEO directory if you want to use the LGEO parts.
APPENDIX B - TROUBLESHOOTING If you run LPub on an MPD file and it does
not produce all the images you expect, the problem is most likely in the format
of the MPD file. LDRAW.org says that the first FILE within an MPD file is the
topmost file in the design. LPub is programmed according to this specification.
If you are having problems with an MPD file, it is probably because it violates
the stated specification. You can edit the MPD file with any text editor and
reformat the MPD to meet LDRAW.org's MPD specification.
If you get this message "Comparing your design to LDRAW's part list showed
parts missing. Cannot process design further", you need to acquire the missing
LDRAW parts listed in LPub's console. You can check LDRAW.prg for the parts,
or search for them on the web. Once located, you need to install them into LDRAW's
PARTS directory and re-run mklist.
BUGS AND LIMITATIONS
I try to fix bugs as soon as I am notified. Currently (temporarily? ;-) there
are no known bugs.
CREDITS AND DISCLAIMERS
LPub is copyrighted and is the property of Kevin L. Clague. LEGO is 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, LGEO, POV-Ray, and
MEGA-POV) are properties of their respective owners.
MLCAD is the property of Michael Lachmann who has so wonderfully devoted his
talents to the LEGO Community. You can get MLCAD and documentation at his site.
B
Blue
G
Green
DC
Dark Cyan
R
Red
M
Magenta
Br
Brown
LB
Light Blue
LG
Light Green
C
Cyan
LR
Light Red
P
Pink
Y
Yellow
Ppl
Purple
O
Orange
TB
Transparent Blue
TG
Transparent Green
TDC
Transparent Dark Cyan
TR
Transparent Red
TM
Transparent Magenta
TBr
Transparent Brown
TLB
Transparent Light Blue
TLG
Transparent Light Green
TC
Transparent Cyan
TLR
Transparent Light Red
TP
Transparent Pink
TY
Transparent Yellow
TPpl
Transparent Purple
TO
Transparent Orange