LDrawParser
A package for parsing LDraw™ files. As stated on the LDraw website, LDraw is an open standard for LEGO CAD programs that enables the creation of virtual LEGO models. This package allows you to parse LDraw™ files into a Julia data structure.
Manual Outline
Example usage:
using LDrawParser
path = "/path/to/ldraw_file.mpd" # or .ldr
model = parse_ldraw_file(path)
model.models
model.partsInstallation
Module
To install the module, run the following command in the Julia REPL:
] add LDrawParserParts Library
It is recommended to download the LDraw parts library to get full use out of your models. Functionality still exists without the parts library, including parsing the build steps, but individual part geometry is recommended for most applications. The parts library can be downloaded from LDraw™ Parts Library. Place the unzipped library in your desired path. The default path assumed by LDrawParser is joinpath(homedir(), "Documents/ldraw"). It is recommended to download the complete library (~80 MB zipped, ~450 MB unzipped).
If you did not place the parts library in the default path, you can change the path LDrawParser uses by the set_part_library_dir! command. For example, if you placed the parts library in the assets directory, you can run the following command in the Julia REPL:
using LDrawParser
set_part_library_dir!("assets/ldraw")Usage
A handful of models are provided in the assets directory. In this example, we are reading in the tractor model and populating the part geometry. We then use the change_coordinate_system! function to change the coordinate system from the LDraw system to the standard right-handed system and scale the model by 0.5.
filename = joinpath(dirname(dirname(pathof(LDrawParser))), "assets", "tractor.mpd")
model = parse_ldraw_file(filename)
# Populate the part geometry
populate_part_geometry!(model)
# Change the coordiante system from the LDraw system to the standard right-handed system and scale model by 0.5
LDrawParser.change_coordinate_system!(model, ldraw_base_transform(), 0.5)Functions
LDrawParser.BuildingStep — TypeBuildingStepRepresents a sequence of part placements that make up a building step in a LDraw file.
LDrawParser.COMMAND_CODE — TypeCOMMAND_CODEThe line type of a line is the first number on the line. The line types are:
- META # 0 !<META command> <additional parameters>
- SUBFILEREF # 1 <colour> x y z a b c d e f g h i <file>
- LINE # 2 <colour> x1 y1 z1 x2 y2 z2
- TRIANGLE # 3 <colour> x1 y1 z1 x2 y2 z2 x3 y3 z3
- QUADRILATERAL # 4 <colour> x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4
- OPTIONAL_LINE # 5 <colour> x1 y1 z1 x2 y2 z2 x3 y3 z3 x4 y4 z4
LDrawParser.DATModel — TypeDATModelEncodes the raw geometry of a LDraw part stored in a .dat file. It is possible to avoid populating the geometry fields, which is useful for large models or models that use parts from the LDraw library.
LDrawParser.FILE_TYPE — TypeFILE_TYPEAll LDraw files carry the LDR (default), DAT or MPD extension.
Official Parts Part | Subpart | Primitive | 8Primitive | 48Primitive | Shortcut Unofficial Parts UnofficialPart| UnofficialSubpart | UnofficialPrimitive | Unofficial8Primitive | Unofficial48Primitive | UnofficialShortcut
The file type is usually prefaced in one of the following ways 0 !LDRAWORG <type> (qualifier(s)) (update-tag) 0 LDRAWORG <type> update-tag 0 Official LCAD <type> update-tag 0 Unofficial <type> 0 Un-official <type>
LDrawParser.META_COMMAND — TypeMETA_COMMAND0 !<META command> <additional parameters>
!is used to positively identify this as a META command. (Note: A few official meta commands do not start with a ! in order to preserve backwards compatibility, however, all new official META commands must start with a ! and it is strongly recommended that new unofficial meta-commands also start with a !)<META command>is any string in all caps<additional parameters>is any string. Note that if a META command does not require any additional parameter, none should be given.
LDrawParser.MPDModel — TypeMPDModelThe MPD model stores the information contained in a .mpd or .ldr file. This includes a submodel tree (stored implicitly in a dictionary that maps model_name to SubModelPlan) and a part list. The first model in MPDModel.models is the main model. All the following are submodels of that model and/or each other.
LDrawParser.NgonElement — TypeNgonElementRepresents geometry from an LDraw file
LDrawParser.OptionalLineElement — TypeOptionalLineElementRepresents optional line geometry from an LDraw file
LDrawParser.SubFileRef — TypeSubFileRefRepresents a sub-file reference from an LDraw file. Encodes the placement of a part or submodel.
LDrawParser.SubModelPlan — TypeSubModelPlanRepresents the sequence of building steps that make up a sub model in an LDraw file
LDrawParser.change_coordinate_system! — Functionchange_coordinate_system!(model::MPDModel, T=ldraw_base_transform(), scale=1.0; ignore_rotation_determinant=false)Transform the coordinate system of the entire model using transform T and scale scale.
LDrawParser.find_part_file — Functionfind_part_file(name,library=get_part_library_dir())Try to find a file with name name, and return that file's path if found.
LDrawParser.get_color_dict — Methodget_color_dict()get dictionary mapping Integer code to color.
LDrawParser.get_part_library_dir — Methodget_part_library_dir()Return the path to the LDraw part library. This is the directory that contains the parts, primitives, and subparts directories.
LDrawParser.ldraw_base_frame — Methodldraw_base_frame()Returns a rotation matrix that defines the base LDraw coordinate system. LDraw uses a right-handed co-ordinate system where -Y is "up"
LDrawParser.load_color_dict! — Functionload_color_dict!(path=joinpath(get_part_library_dir(),"LDConfig.ldr")))Load dictionary mapping Integer code to color.
LDrawParser.parse_ldraw_file — Methodparse_ldraw_file(filename)
parse_ldraw_file(filename; sneaky_parts::Set{String}=preprocess_ldraw_file(filename),
ignore_rotation_determinant::Bool=false)Parse an LDraw file and return an MPDModel. Files can be .mpd or .ldr files.
Keyword Arguments:
sneaky_parts::Set{String}: A set of part names that are masquerading as submodels.
Often not needed to include this argument, as it is automatically generated by preprocess_ldraw_file. (default: preprocess_ldraw_file(filename))
ignore_rotation_determinant::Bool: If true, ignore the determinant of the
rotation matrix. Some parts have rotation matrices with negative determinants. This does not affect rendering, but can cause issues with other operations. (default: false)
LDrawParser.populate_part_geometry! — Functionpopulate_part_geometry!(model,frontier=Set(collect(part_keys(model))))Load all geometry into model.parts. Loading is recursive, so that geometry will be loaded through arbitrary levels of nested subparts until finally being stored in each atomic part that is referenced by the main model(s).
LDrawParser.preprocess_ldraw_file — Methodpreprocess_ldraw_file(io)Return a set of part names that are masquerading as submodels.
LDrawParser.read_line! — Methodread_line!For reading lines of type LINE
LDrawParser.read_meta_line! — Functionread_meta_line(model,state,line)Modifies the model and parser_state based on a META command. For example, the FILE meta command indicates the beginning of a new file, so this creates a new active model into which subsequent building steps will be placed. The STEP meta command indicates the end of the current step, which prompts the parser to close the current build step and begin a new one.
LDrawParser.read_optional_line! — Methodread_optional_line!For reading lines of type OPTIONAL_LINE
LDrawParser.read_quadrilateral! — Methodread_quadrilateral!For reading lines of type QUADRILATERAL
LDrawParser.read_sub_file_ref! — Methodread_sub_file_refReceives a SUBFILEREF line (with the leading SUBFILEREF id stripped)
LDrawParser.read_triangle! — Methodread_triangle!For reading lines of type TRIANGLE
LDrawParser.set_part_library_dir! — Methodset_part_library_dir!(path)Set the path to the LDraw part library. This is the directory that contains the parts, primitives, and subparts directories.