PreL3P

PreL3P preprocesses LDraw files for color compatibility with L3P, which converts LDraw models to POV-Ray format. The current version of L3P (1.3) only knows about some color codes, but it does support arbitrary colors via an extended color syntax. PreL3P replaces LDraw color codes unrecognized by L3P with hexadecimal “extended color” specifications based on the COLOUR definitions provided by your LDraw configuration file. No special material tags are honored besides ALPHA 128 (regular transparency). Color codes can also be mapped directly to other color codes.

PreL3P is a hack to allow models containing contemporary colors to be rendered with L3P and POV-Ray without touching any POV-Ray code. It is not intended to replace other, more expert, solutions to the color quandary; better results can arguably be had by manually including custom POV-Ray color definitions. Ideally, L3P and other programs like Bricksmith would support ldconfig.ldr themselves.

Usage

prel3p # Default: [-in FILE] # stdin [-out FILE] # stdout [-ldconfig FILE] # LDRAWDIR/ldconfig.ldr [+codes none|l3p|CODE[,...]] # l3p (keep codes known by L3P) [-codes none|l3p|CODE[,...]] # none (preprocess all others) [-map IN:OUT] # no mappings [-flag quiet] # not quiet (report completion) [-flag noglob] # glob expansion supported [FILE[,...]] # none (see Alternate Usage) 

Explicit option values override the defaults.

PreL3P can be used as a filter:

prel3p < input.ldr > output.ldr 

Output is not written until the input has been successfully parsed and processed, so files can be preprocessed in place:

prel3p -in model.ldr -out model.ldr 

The codes options permit custom substitution schemes to be specified. The + and - characters represent color codes which should be preserved and color codes which may be replaced, respectively.

prel3p +codes 0 # replace any code other than 0 (black) prel3p -codes 0,71,72 # replace codes 0, 71, and 72, but no others prel3p +codes l3p -codes 4 # preserve color codes known to L3P, except 4 prel3p +codes none # replace every color code (preserve none) 

Unspecified codes are handled according to the behavior implied by the type of the first codes option. +codes implies that other codes may be replaced; -codes implies that other codes should be preserved. Subsequent options of either type modify the initial set.

Color codes can be renumbered with the -map option. For instance, to replace instances of color code 7 with color 8, specify -map 7:8. Mapping occurs before substitution, so if -codes 8 is also specified and a !COLOUR definition for 8 is found, instances of 7 will ultimately be replaced by the hexadecimal equivalent of 8.

A message reporting how many colors were changed and how many lines contained changes is printed when processing is complete. Mappings and color substitutions both constitute color changes.

Color definitions are normally read from LDRAWDIR/ldconfig.ldr (LDRAWDIR is an environment variable assumed to contain the path to your LDraw directory). Different configuration files may be specified with the -ldconfig option. Multiple -ldconfig options may be given, in which case the last of multiple definitions for the same color code takes precedence.

With the exception of color codes, PreL3P’s output is identical to its input. Whitespace, capitalization, and decimal precision are not modified. Unrecognized lines are preserved, as are unrecognized color codes (those not identified by the ldconfig file).

Alternate Usage

If no -in or -out arguments are specified, PreL3P will interpret unrecognized arguments as paths to files to process.

prel3p model.ldr 

The original model.ldr is copied to model.ldr.bak and the processed version is saved in place as model.ldr.

In this context PreL3P understands glob wildcard characters. For instance, in a directory containing only the files model1.ldr, model2.ldr, and model3.ldr, the following commands are equivalent:

prel3p model*.ldr prel3p model?.ldr prel3p model[1-3].ldr prel3p model{1,2,3}.ldr prel3p model1.ldr model2.ldr model3.ldr 

This feature is intended primarily as a convenience for Windows command prompt users since this functionality is typically provided by the command line shell itself on other platforms (unless the argument is quoted). Wildcard expansion can be disabled with the -flag noglob option.

Meta Commands

In addition to the !COLOUR meta command, PreL3P understands unofficial meta commands which allow certain PreL3P command line options to be imbedded in models and configuration files.

The general form of these meta commands is:

0 !PREL3P OPTION VALUE 

where OPTION is one of -ldconfig, +codes, -codes, or -map and VALUE is formatted as the analogous command line parameter.

Options and !COLOUR definitions are read from the input model header after command line options are parsed. The model header is comprised of all input lines preceding the first instance of any LDraw type 1 through 5 lines. Configuration files specified by -ldconfig options in the model header are appended to the configuration file queue and override the default -ldconfig if no explicit value is given on the command line.

Configuration files are parsed sequentially after reading the model header. The entire configuration file is read; LDraw type 1 through 5 lines are ignored. Additional configuration files specified by -ldconfig meta commands within configuration files are parsed at the point they are encountered.

PreL3P meta commands in the model that are not in the model header are parsed and applied as they are encountered during processing. This allows different color substitution schemes to be used for different parts of the model.

Example

Here is a simple LDraw file, bricks.ldr. It uses color codes 89 (Royal Blue), 92 (Flesh), and 72 (Dark Stone Gray).

1 89 0 0 -20 1 0 0 0 1 0 0 0 1 3005.dat 1 92 0 0 0 1 0 0 0 1 0 0 0 1 3005.dat 1 72 0 0 20 1 0 0 0 1 0 0 0 1 3005.dat 

L3P doesn’t recognize these color codes, so it replaces them with the default color 7 (Gray). As a result, the initial rendering looks like this:

So, let’s use PreL3P to make a copy of the model with colors L3P can understand:

prel3p -in bricks.ldr -out prebricks.ldr 

The contents of prebricks.ldr:

1 0x029BB2EF 0 0 -20 1 0 0 0 1 0 0 0 1 3005.dat 1 0x02CC8E68 0 0 0 1 0 0 0 1 0 0 0 1 3005.dat 1 0x02635F61 0 0 20 1 0 0 0 1 0 0 0 1 3005.dat 

L3P converts this version of the model without complaint, and the final rendering looks like this:

Changes

1.1:

• Added “done” announcement and statistics with complementary -flag quiet option.
• Multiple -ldconfig FILE option pairs may be given.
• Added alternate usage syntax.

1.2:

• Added -map option to convert color codes directly to other codes.
• Added !PREL3P meta command versions of -ldconfig, +code, -codes, and -map.
• Added -help option to display brief usage summary.
• Tweaked alternate usage backup mechanism.

1.3:

• Meta commands may be used throughout models.

1.3.1:

• Properly report a few errors.
• Limit number of -ldconfig references to prevent circular references.

1.4:

• Added ability to process multiple files
• Added support for wildcard characters

Download

• prel3p-1.4-kit.zip 14 KB
  Platform independent Starkit. Requires a separate Tclkit (8.4.16 recommended).
• prel3p-1.4-mac.zip 1.9 MB
  Self-contained universal binary (x86 + PPC) for Mac OS X 10.4+.
• prel3p-1.4-mac-service.zip 2 MB
  Macintosh Starpack bundled as a service for filtering selected text. Install in ~/Library/Services/.
• prel3p-1.4-win.zip 559 KB
  Self-contained console binary for Windows.

The source code may be extracted from any version with SDX. An example localization file is available here.

Posted on Saturday, October 6th, 2007. Tags: l3p, LDraw, LEGO, prel3p, tcl.