Objects in GDL are usually created and used as binary objects with .gsm extension.
This is very convenient when you, as a developer, only want to create a few objects at a time, and you are not planning on updating or developing them any further for upcoming versions.
This can be sufficient in a lot of cases.
However, once you start developing bigtime, working with complete libraries of objects, storing and modifying your files may be more convenient using a human-readable source format.
There are two source formats: XML and HSF. The XML format stores one library part in one .xml file plus separate binary images. The
ARCHICAD is shipped with a built-in tool for converting between binary (gsm or lcf) and source (xml or hsf) formats:
the LP_XMLConverter tool does the trick both ways, and can do a lot more than that as well.
Every binary library part can be broken down into text (and separate binary image) files, containing all the information and scripts necessary to rebuild them as binary objects. Data are represented between XML tags. Very easy to identify the parts, once you examine it a bit more closely.
Opposite to binary, the text format can be used in any code editor:
- easy find and replace functions for multiple elements
- easy to change the default of a parameter
- easy to add/remove parameters (without using a custom subtype)
- developing similar elements is a lot faster
- built-in images for UI and preview are available
- version update may be easier
- script highlighting may be available
- localization can be automated using dictionaries
Accessing the LP_XMLConverter
This is platform dependent.
On Windows:
the tool is located in the main installation folder of ARCHICAD: LP_XMLConverter.exe.
Open a command prompt, and drag&drop the executable file into it.
On OSX:
In Finder, right click on ARCHICAD.app, “Show Package Contents”. The LP_XMLConverter.app is located in Contents/MacOS.
Look into the Contents of the converter app as well, and look for the executable version of the app in Contents/MacOS.
Open a Terminal window, and drag the executable file there.
The next step is to give some input parameters for the converter. This is the same on both platforms.
To get all the available options, type help after the command and hit ENTER.
Lets take a look at the most commonly used functions.
Converting a single file
Conversion to XML
The command for this is libpart2xml.
Usually you start with a .gsm saved from ARCHICAD to a custom folder. The path of this saved binary is the “binaryFilePath”.
Then, create an empty file with .xml enxtension. The path of this file is going to be the “xmlFilePath”. If you do not want to create it in advance, make sure you type the destination path correctly.
Give the necessary parameters to the converter:
"pathOfLP_XMLConverterExecuteable" libpart2xml "binaryFilePath" "xmlFilePath"
The easiest way is to drag and drop the source and destination files into the command prompt, so the operation system takes care of special character escaping and such.
After running the converter with these parameters, the resulting file should be a text file containing scripts, parameter sections, etc. Built-in pictures are not extracted in this case, they will appear in your XML files as binary data.
If you want the pictures (UI and Preview) extracted, add the -img “imageFolderPath” extension of the command:
"pathOfLP_XMLConverterExecuteable" libpart2xml -img "imageFolderPath" "binaryFilePath" "xmlFilePath"
This way all built-in images will be extracted to the given folder.
Conversion to HSF
The command for this is libpart2hsf.
Similarly to the XML conversion the binary file path should be given, and a folder path, in which the library part will be created in HSF format within a subfolder with the binary file’s name:
"pathOfLP_XMLConverterExecuteable" libpart2hsf "binaryFilePath" "hsfFolderPath"
The -img command of the LP_XMLConverter has no effect in case of HSF conversion, as the built-in image library is always in the library part’s HSF folder, under the name of images.
Conversion to .gsm
To compile it back from XML format, change the order of the input parameters and use this command: xml2libpart:
"pathOfLP_XMLConverterExecuteable" xml2libpart -img "imageFolderPath" "xmlFilePath" "binaryFilePath"
To compile it back from HSF format, use the hsf2libpart command. At HSF conversion not only the order of the input parameters should be changed, but the the library parts’ HSF folder itself should be given as the source folder:
"pathOfLP_XMLConverterExecuteable" hsf2libpart "hsfLibraryPath" "binaryFilePath"
These commands compile your .xml file and images or HSF folder into a complete .gsm binary again.
Converting a complete folder with built-in images
If you have multiple binaries in a folder, you can turn the complete folder into texts and pictures with some modification of the above.
Conversion to XML
First, use the command l2x to convert folders, and use corresponding folder paths instead of file paths:
"pathOfLP_XMLConverterExecuteable" l2x -img "imageFolderPath" "binaryFolderPath" "xmlFolderPath"
The result will be structured in the destination folder similar to binary folder. Images will be extracted into subfolders of imageFolderPath named after the corresponding library parts.
Conversion to HSF
Similarly to the XML conversion, HSF conversion can be done with the l2hsf command.
"pathOfLP_XMLConverterExecuteable" l2hsf "binaryFolderPath" "hsfFolderPath"
The -img command has no effect in case of HSF conversion, as the image library is always in the library part’s folder, under the name of images.
Conversion to .gsm
To create binaries again from XML format, use x2l:
"pathOfLP_XMLConverterExecuteable" x2l -img "imageFolderPath" "xmlFolderPath" "binaryFolderPath"
From HSF format, use hsf2l:
"pathOfLP_XMLConverterExecuteable" hsf2l "hsfFolderPath" "binaryFolderPath"
Recommendation:
use the following folder system to store all your libparts and data:
- Library_src: a folder for your .xml or HSF source files
- Library_images: for image files (only with XML format). This should be located in the same folder as your folder containing the .xml files, for convenience (the path of corresponding images is stored in the XML)
- Library: a folder for your binaries