Graphisoft®

Basic Library Version: 13

User Documentation
of the LP_XMLConverter tool

Index

  1. Abstract
  2. File formats of the tool
    1. Library Part Files
    2. XML Files
  3. Parameters and running
    1. Convert directory trees
    2. Convert files
    3. Fix the hierarchy of a library
    4. Make a full library
    5. Handle container files
    6. Make subset library
  4. Usage tips
    1. Compilation for two platforms
    2. Handling built-in images
    3. Hiding script sections
    4. Localization of default values

1. Abstract

The LP_XMLCoverter tool compiles XML files of a given format to ArchiCAD® Library Parts and vice versa on Windows and Macintosh platforms. Usage of the tool faciliates the creation process of ArchiCAD Libraries by the benefit of a cross-platform text-based format for the time of development.

This documentation applies for Version 2.6.0.

2. File formats of the tool

The tool uses and generates XML and library part files. A library part file can be unequivocally transformed to one XML file and vice versa without losing any data (when using a correct codepage for transcoding, special characters may get lost otherwise).

The file names must comply with the codepage set in the Regional Settings of the operating system. For example you won't be able to compile a library with Greek file names on Western Codepage.

2.1 Library Part Files

The generated files are ArchiCAD library part files with version 23. Consider the main attributes of this file format.

Library Part Identification

In short, two GUIDs - internally coded long numbers -, in combination with the object file name, identify each object. This identifier is called the Library Part ID and it helps ArchiCAD track the iterations of an object, as it is revised or improved. The ID consists of two parts: the first part is the Main ID and the second represents the Revision ID.

The Main ID is created when the library part is saved for the first time. It is also modified if a new library part is created based on an other using the "Save as" command.

The Revision ID is also created when the library part is saved for the first time but it is modified if the library part is resaved using the "Save" command. Using the LP_XMLConverter tool a compilation will change the Revision ID and leave the Main ID untouched, of course.

This means that the Main ID identifies a library part in its function and the Revision ID helps in distinguishing the revisions of the object.

For more information refer GDL Technical Standards Chapter 2 (part of the Basic Library Documenation).

Encoding

The encoding of the texts is UTF-8 from ArchiCAD 11 on.

2.2 XML Files

The XML files are stored in UTF-8 encoding and the line breaks are UNIX linefeeds. The XML format is defined as XML Document Type Definition (DTD) and as XML Schema Definition (XSD) as well.

All binary sections of the library part - which are not resolved into XML elements - are saved with Windows byte order.

These properties quarantee the full platform independence of the XML format of library parts.

3. Parameters and running

The tool has some distinct functionalities. These can be grouped into five types as follows.

3.1 Convert directory trees (of XML or library part files)

LP_XMLConverter l2x [-l lang] [-img folder] [-cur file [-keepimagepath]] source dest

Converts all library parts (.gsm files) in the given (source) directory tree to XML files into the given (dest) directory recursively. Other files will be copied as binary files (images, .txt, .gdl etc.).

-l lang
Language identifier for text conversion codepage: INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR.
-img folder
Location of the image folder to create. The images in each library part will be extracted from the GSM file into subfolders and they will be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict) in the created XML files. See chapter Handling built-in images.
-cur file
Location of the current replacement XML file. See chapter Localization of default values.
-keepimagepath
Keeps the path and the filename of the images defined in section GDLPict and Picture. If you don't use this specifier, the path will be determined by the path of the library part and the ID of the picture.
source
Source directory of the library parts to convert, the directory must exist.
dest
Destination directory for the converted XML files, the parent of the directory must exist.
LP_XMLConverter x2l [-l lang] [-img folder] [-def file [-cur file [-keepimagepath]]] source dest

Converts all XML files in the given (source) directory tree to library parts into the given (dest) directory recursively. Other files will be copied as binary files (images, .txt, .gdl etc.).

-l lang
Language identifier for text conversion codepage: INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR.
-img folder
Location of the image source folder. The images can be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict). The compiled library parts will contain the images in themselves. See chapter Handling built-in images.
-def file
Location of the meaning definition XML file. See chapter Localization of default values.
-cur file
Location of the current replacement XML file. See chapter Localization of default values.
-keepimagepath
Keeps the path and the filename of the images defined in section GDLPict. See chapter Localization of default values.
source
Source directory of the XML files to convert, the directory must exist.
dest
Destination directory for the converted library part files, the parent of the directory must exist.

3.2 Convert files (XML or library part files)

LP_XMLConverter libpart2xml [-l lang] [-cur file [-keepimagepath]] source dest

Converts the library part file at the location source to an XML at the location dest.

LP_XMLConverter xml2libpart [-l lang] [-img folder] [-def file [-cur file [-keepimagepath]]] source dest

Converts the XML file at the location source to a library part at the location dest. If there was a library part at the location dest, it is deleted first.

LP_XMLConverter copysections [-l lang] source dest
		[section_name [section_type_id] [sub_ident] ...]

Copies the specified sections from the source library part file to the dest XML file.

-l lang
Language identifier for text conversion codepage: INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR.
-img folder
Location of the image library. The images can be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict). See chapter Handling built-in images.
-def file
Location of the meaning definition XML file. See chapter Localization of default values.
-cur file
Location of the current replacement XML file. See chapter Localization of default values.
-keepimagepath
Keeps the path and the filename of the images defined in section GDLPict. See chapter Localization of default values.
source
Location of the source file of the conversion. The file must exist.
dest
Location of the destination file of the conversion. The parent directory must exist.
section_name
Name of the section to copy from the library part to the XML file. Possible values: SubKind, Drawing, Script_3D, Script_2D, Script_1D, Script_VL, ParamSection, Picture, Ancestry, CalledMacros, Script_UI, Comment, Script_PR, Binary3D, InfoPict, GDLPict, UnknownSection, UNID. If 'UNID', the unique ID of the libpart is copied.
section_type_id
Valid only if section_name is 'UnknownSection'. Specifies the unsigned long value of the section type.
sub_ident
Can specify the subident value of the section to copy. If missing, the default value is 0.

3.3 Fix the hierarchy of a library

LP_XMLConverter fixhierarchy libraryLocation [additionalLib ...]

Repairs the ancestry information, the version, the macro-call section and the parameter section of each library part file in the libraryLocation directory tree. Every changed library part gets a new rev-ID.

libraryLocation
Location of the (GSM) library to fix.
additionalLib
Locations of additional binary libraries. These libraries are used in fixing the references between library parts (which is based on library part IDs - see GDL Technical Standards Chapter 2.2 for details)

3.4 Make a full library

These commands are intended to serve in a make system, where libraries are developed. All of them check whether an XML file changed since the last compilation. For this, the IDEntryList.dbe file is used. In this file, the tool stores the ID and the MD5 checksum of all the source files. This data is used for each file as follows:

Non-XML text files (.gdl and .txt) can be stored in Unicode coding, character coding will be transformed to the givel local codepage. Non-XML binary files will be copied unchanged (images and everything except the XML and the foregoing text files).

LP_XMLConverter convertlibrary [options] source dest
Compiles a directory tree of XML files to a directory tree of library parts.
LP_XMLConverter convchecklibrary [options] source dest
Compiles a directory tree of XML files to a directory tree of library parts and checks the consistency of the whole library (ancestry information and macro-call section).
LP_XMLConverter makelibrary [options] source dest [additionalLib ...]
Compiles a directory tree of XML files to a library with a correct hierarchy. So this variant makes a convertlibrary and a fixhierarchy in succession.
LP_XMLConverter finalizelibrary [options] source dest [additionalLib ...]
Does makelibrary and updates 4 sections of the the XML files. These sections are: UNID, Ancestry, CalledMacros, ParamSection. These sections change by re-saving the file (because of the GUIDs) and fixing the inconsistencies (done by fixhierarchy).

The options are: [-l lang] [-s "suffix"] [-img folder] [-check level] [-verbose n] [-def file [-cur file [-keepimagepath]]]

-l lang
Language identifier for text conversion codepage: INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR.
-s "suffix"
Optional suffix for names of all target folder. It can be used to distinguish library versions (e.g. Basic Library 9).
-img folder
Location of the image library. The images can be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict). See chapter Handling built-in images.
-def file
Location of the meaning definition XML file. See chapter Localization of default values.
-cur file
Location of the current replacement XML file. See chapter Localization of default values.
-keepimagepath
Keeps the path and the filename of the images defined in section GDLPict. See chapter Localization of default values.
-check checkingLevel
Level of checking done during the compilation - all tests are additional in the ascendent levels:
0
No checking
1
Checking GDL Errors
2
Checking Pictures
3
Checking generic GDL warnings
4
Checking .GDL files
5
Checking precision warnings
6
Checking interpretation errors using the default parameters
7
Checking uninitialized variables during interpretation
-interface fileName
Macro library interface definition XML file. When compiling a library without the interface parameter specified, the tool will report all unused macros in separate warnings. In case of a macro library unused macros are the natural intention of the creator and these warnings would shroud other important problems. Consequently, macro libraries should specify their public interface in an XML file (and pass the file to the tool) to omit unused macro warnings for the published macros. The format of the XML file is specified in the XML Schema for Interface Definition file.
-verbose verbosityLevel
Option for setting the verbosity level of printed messages:
0
Quiet mode
1
Print compile information (default)
2
Print all process information
source
Source directory of the compilation.
dest
Destination directory of the compilation.
additionalLib
Locations of additional binary libraries. These libraries are used in fixing the references between library parts (which is based on library part IDs - see GDL Technical Standards Chapter 2.2 for details)

3.5 Handle container files

A library package can be stored in a Library Container File (LCF) subserviently. The LP_XMLConverter can create and extract such an LCF with the following commands.

LP_XMLConverter createcontainer containerFile [-l lang] [-compress level] libraryFolder [...]

Creates an LCF on the location containerFile containing the passed libraries.

containerFile
Location of the container file to create.
-l lang
Currently it is ignored.
-compress level
Compression level setting. The level must be in the 0 - 9 range. 0 means no compression, 1 is best speed, 9 is best compression. The default is 0.
libraryFolder
Location of one or more library folders which are to be included in the container file.
LP_XMLConverter extractcontainer containerFile [-l lang] libraryFolder

Extracts the LCF on the location containerFile to the libraryFolder folder.

containerFile
Location of the container file to exract.
-l lang
Currently it is ignored.
libraryFolder
Location of a destination folder to contain the content of the LCF to extract.

3.6 Make subset library

The LP_XMLConverter can create a subset library with the following parametrization. A subset library is the one-sided difference set based on an earlier and a new version of the same library.

Let’s take AC10Lib and AC11Lib for example. Their subset will contain all library parts from AC10Lib which don’t have a compatible equivalent in AC11Lib. These can be:

  1. Elements, which are not supported anymore and got deleted.
  2. Elements, which were changed in an incompatible way and got a new Main ID.
LP_XMLConverter makesubsetlibrary previous current subset
previous
Source location of the previous library in XML. The folder must exist.
current
Source location of the current library in XML. The folder must exist.
subset
Target location of the subset library to be created in XML. The specified folder will be created.

5. Usage tips

5.1 Compilation for two platforms

Note, that XML files are cross-platform, GSM files are not. (But ArchiCAD can use GSM files from both platforms)

The tool compiles the XML files to a GSM-library for the platform, on whitch it was started. We want to avoid the variance of revision ID-s of the same library part on Windows and on Mac. Different revision ID-s slow down the usage of cross-platform project files a bit. Follow these steps to generate correct libraries with fitting ID-s on both platforms:

5.2 Handling built-in images

Library parts can contain "built-in" images. LP_XMLConverter eases the access of this feature, too.

The steps of usage are the following:

  1. Create a folder for the image files and place images in it. The images can be of any format known by ArchiCAD.
  2. Refer the images from the XML files using the following syntax:
    <GDLPict MIME="image/png"
        path="subfoldername/filename.png"
        SubIdent="3"
        platform="Win"
        SectVersion="19"
        SectionFlags="0">
    </GDLPict>
    The path is relative to the main image folder, which is passed to the converter via the -img commandline parameter. SubIdent is the inner identifier of the image. This ID can be used to access the image from the scripts. In case of using -keepimagepath commandline option, these filenames are invariable after the conversion. Otherwise the filenames become subfoldername/GDLPict_X.ext, where X is the inner identifier of the image ('SubIdent').
  3. Use the image in the scripts of the library part containing it. The actual image can be identified by the SubIdent value, as this example shows:
    UI_INFIELD "parName", xPos, yPos, width, height,
            1, 3, 5, 1,        ! mind the "3"
            56, 50, 40, 40,
            1, "",
            2, "",
            3, "",
            4, "",
            5, ""

5.3 Hiding script sections

Library Parts provide a way to have the scripts hidden from the end user. This can be done in XML by adding 64 to the SectionFlags attribute of the script to be hidden. This will create a GSM file with the given scripts hidden. Converting a library part with hidden scripts back to XML will create empty script elements, so be sure to keep the original XML files after publishing the library.

5.4 Localization of default values

Some published libraries should work with different default attribute sets - consequently they must come with different default parameters to different users. Since ArchiCAD 11, LP_XMLConverter provides a way to compile differently parametrized libraries from the same source XMLs. The technology is based on the concept of meanings.

meanings give you the possibility to assign architectural notion to a given parameter. See the following example from the International ArchiCAD Library's Armchair 01.xml where we assert that the value of 4 in the gs_cont_pen parameter is just an instance of the notion of Furnishing_ContPen (which is meaningful architectural thing in contrast to '4').

<PenColor Name="gs_cont_pen">
	<Description><![CDATA["Contour Pen"]]></Description>
	<Fix/>
	<Flags>
		<ParFlg_Child/>
	</Flags>
	<Value Meaning="Furnishing_ContPen">4</Value>
</PenColor>

Having this asserted, you can define the default values for all meanings you specified. This can be done in a so called replacement definition XML file. Here is a snipplet from it which tells the converter tool to substitute all furnishing contour pens with 7 in the current compliation.

<ReplacementDef>
	<ReplacementItem meaning="Furnishing_ContPen" value="7"/>
	...
</ReplacementDef>

Unfortunately, the GSM library part format cannot hold these extra meaning hints, consequently an extra file beside the binary library must be created in this substituting scenario. This extra file is the current replacement file and it is used when you convert the binary GSM-s back to XML - to restore the original values and meanings.

These two files can be passed to the converter tool using the -def and -cur parameters, accordingly.

The paths of built-in image files get stored in this file, too, in case you add the -keepimagepath specifier. See chapter Handling built-in images for further info.