Example objects for this post

In ARCHICAD 23 a new source format has been introduced for handling the GDL objects as text files: the Hierarchical Source Format (HSF). This post introduces the parts of this source format and flies through the conversion of a library from XML format to HSF format.

Note: The advantages and tools for handling libraries in text format instead of binary format are described in the How to use the LP_XMLConverter tool? post.

HSF Contents

Before ARCHICAD 23 a .gsm library part could be converted only to XML source format, where a single .xml file is created, in which the information and the scripts are separated by nametags. If the .gsm library part is converted to a HSF format, the scripts and different kind of information are separated into different files with the following folder structure:

[<LIBPARTNAME>]
    [binaries]
        fragment2.xml
        binary3d.bin
    [images]
    [scripts]
        1d.gdl
        2d.gdl
        3d.gdl
        ui.gdl
        pr.gdl
        vl.gdl
        fwm.gdl
        bwm.gdl
    ancestry.xml
    calledmacros.xml
    libpartdata.xml
    libpartdocs.xml
    migrationtable.xml
    paramlist.xml

All the files are in a folder named as the binary .gsm library part. When a .gsm file is reverted to HSF format the ancestry.xml, calledmacros.xml, libpartdata.xml, libpartdocs.xml and paramlist.xml files are always created. The other files and folders are only created if they contain data. If you add a new file in the HSF folder it should have UTF-8 encoding with BOM.

libpartdata.xml

This XML file contains the metadata needed for identifing the library part itself and to define the content of the library part. It contains the main GUID and attributes of the library part and references to all the used sections in the HSF file tree.

ancestry.xml

The subtype hierarchy of the library part is stored in the ancestry.xml file.

paramlist.xml

The paramlist.xml file contains the whole parameter section: the parameters themselves and the parameter section header.

calledmacros.xml

This file contains the called macros section: the names and GUIDs of the macros called by the library part.

libpartdocs.xml

This file contains the Keyword, Comment and the Copyright sections.

migrationtable.xml

This file contains the Migration Table for migration handling. When a .gsm file is reverted to .hsf format this file is only created if the .gsm file had data in its migration table.

scripts

Each script with any content in it appears as a .gdl file with a fixed name referring to the script type. A .gdl file is plain-text code that can be copied to an from the GDL editor.

images

The HSF format contains the library part’s built-in images. The -img command of the LP_XMLConverter 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.

binaries

If the library part contains non-script-based models, the 2D models are converted to fragment2.xml, the 3D models are converted to binary3D.bin file. Both of the files are created under the binaries folder.

Converting Library parts to .hsf

In order to convert your XML library to HSF, first the XML library should be converted to .gsm files, using the LP_XMLConverter.

The .gsm conversion to .hsf format is based on the same method as the .xml conversion. The recommended commands are l2hsf and hsf2l, but the libpart2hsf and hsf2libpart commands written at the help of the LP_XMLConverter can be used as well for single file conversion.

Single file conversion

A single .gsm file can be converted to HSF format with the libpart2hsf command:

"pathOfLP_XMLConverterExecuteable" libpart2hsf "binaryFilePath" "hsfFolderPath"

Note that the hsfFolderPath does not contain the library parts’ folder name, the library part will be created under the hsfFolderPath directory.

To convert the library part back to .gsm format the library parts’ HSF folder itself should be given as the source folder:

"pathOfLP_XMLConverterExecuteable" hsf2libpart "hsfLibraryPath" "binaryFilePath"

Complete folder conversion

A folder containing binary .gsm files can be converted to a folder containing the library parts in HSF format:

"pathOfLP_XMLConverterExecuteable" l2hsf "binaryFolderPath" "hsfFolderPath"

Note that the hsfFolderPath does not contain the library parts’ folder name, the library part will be created under the hsfFolderPath directory.

The folder containing the HSF library parts can be converted back to a folder containing .gsm files:

"pathOfLP_XMLConverterExecuteable" hsf2l "hsfFolderPath" "binaryFolderPath"

Built-in image handling

As the -img command has no effect, the built-in images are converted with their names in the .gsm file. The .gsm file image names are always generated automatically: Picture_0, GDLPict_1, GDLPict_2, … ect., so check the image names of your converted library and rename them if necessary.