Library Design

Index

1. Introduction

This document contains some major principles and some useful tips for the design of GDL libraries. These guidelines shall to help you in creating an ArchiCAD conform, user-friendly library.

2. Library Design Principles

2.1 General Requirements

Libraries released by Graphisoft must:

• be compatible with each other. To ensure compatibility, developers have to follow Graphisoft's library and object standards.
• give the fastest and easiest solutions for the users by using the minimum number of objects and parameters.
• work error free on Windows and Macintosh platforms. Developers have to provide both Windows and Macintosh versions unless otherwise requested by Graphisoft or the customer.
• be organized into logical directory structures. The names of the directories, objects and parameters have to be consistent and have to refer their function.
• work error free under all possible parameter combinations (this applies to the full content). Parameter values and parameter combinations have to be kept between valid limits by parameter scripting. See chapter 3.1

2.2 Directory Structure

The library content has to be kept in a logical and well-arranged directory structure. New ArchiCAD libraries must follow the structure of previous releases, unless Graphisoft advises changes. In other libraries for other products, the directory system has to meet customer's needs and/or national standards (e.g., CIS).

• The library system has to be ergonomic. Keep the number of directory levels under six to make library browsing faster.
• Do not mix different types of objects (door, window, macro object, etc.) within the same folder.
• Additional files (macros, macro objects, master GDL scripts, textures, etc.) required by the objects have to be kept in subfolders. When objects in different folders use the same macros or textures, we suggest that you create a Macro and a Texture folder in the root directory of the library.
  ArchiCAD differentiates between functional image types by the container folders name:
  • [TImg]* : files in folder are textures
  • [BImg]* : files in folder are background images
  • [UImg]* : files in folder are utility images (e.g. for UI tabpage)
• Libraries cannot contain elements with identical names, even if these files have different extensions (e.g., tree.gsm, tree.jpg etc.). Such files have to be renamed.

2.3 Folder and file names

• File and folder names must refer their function.
• Element or folder names have to be as short as possible to make library browsing faster. Length of the object names cannot exceed 27+1+3 characters. ArchiCAD won't load files or folders with longer names.
• Do not use special characters in file and folder names (@ # ! $ % µ ¼ ß etc.).
• All folder names in ArchiCAD libraries have to end with a one or two-digit code that indicates the version of ArchiCAD the library was made for (e.g., BASIC LIBRARY 8.1). The LP_XMLConverter tool arranges this for the whole library when asked for. The library part names shouldn't end with version number, this will let the user change library in a plan file.
• All folder and element names in Graphisoft Collection libraries have to end with a three-character code referring the type of the library (e.g., Log Sofa LHL.gsm in Log Home Library).
• In other projects a custom identifying code has to be introduced that relates to the function of the library. If there is a national standard for naming objects or libraries we advice you to use it (e.g., CIS system in the US).

3. Library Part Design Principles

3.1 Parameters

The number of additional parameters in the objects must be reduced to the possible minimum. Users are confused by too many parameters.

Parameters have to be arranged in a logical system in all library parts. If you have more than 5-10 parameters, arrange them with title parameters. See ArchiCAD library parts for reference.

The parametrizing logic must be reflected in the arrangement of the parameters: groups of parameters should be created and the connection between them must be defined clearly (later implemented in the Parameter Script). To accomplish this, links between different parameters must be carefully analyzed.

Automatic reset of parameters (using commands like range, parameters) should be used carefully. Keep in mind that:

• Automatic changes won't always give the result that the user expects.
• A circular parameter reset must be avoided (e.g., changing X resets Y, which in turn resets Z, which resets X again).

Identical functionality has to have the same parameters and parameter names in all objects to allow modifications on multiple selected objects. Graphisoft's standard parameter names are used in the international library objects.

Valid parameter values, ranges and parameter combinations have to be well defined in order to avoid error messages caused by invalid parameters.

Lock (gray out) or hide unusable or fixed parameters. Graying out should be used if the parameter value is important even though it cannot be set; use hiding otherwise. Display the real values of locked parameters.

Please note that objects that have array value parameters don't work with the GDL Object Web Plugin.

If you want to use custom materials in more applications (ArchiCAD, Web Plug-in, GDL Explorer), define a text type parameter for the names of them.

3.2 2D model

Plan symbols have to be typical of the elements and have to be in compliance with national and international drawing standards.

Make plan symbols simple and recognizable for faster plan browsing.

Remember that the 2D model can display in the following contexts:

floor plan

the main goal for 2D model

settings dialog

the model works as a preview (128x128 pixel sized view!)

section / elevation

2D object on a section drawing

detail drawing

the model is a part of a detail drawing

feedback mode on floor plan / section drawing

model must be simplyfied for quick generation

Only the necessary hotspots have to be shown on the symbol. The default hotspot has to be the typical point for placing the element (e.g., the center point of a column).

Make elements' hotspots editable on 2D plan and in 3D view when it is reasonable.

From ArchiCAD 9 on you can add status lines to the 2D model of your objects. Use this option for a good reason only since it slows down the work with the library part in 2D (f.ex. place status line on the axis of the handrail of a stair but don't place status lines on the edge of each step).

Create background fills for all the objects to hide fills and zones under their symbol. Make the background fill type, pen and contour pen adjustable. The user can set transparent fill when it is desired (it may be the default, too).

Plan symbols have to be scale-sensitive whenever possible (typically doors and windows). Custom linetypes, fills and texts can be defined scale sensitive or scale independent. Take this into consideration when making plan symbols.

Avoid placing texts in the binary 2D symbol (especially error messages) in order to make localization easier. Use a 2D script for defining texts in order to make them scale sensitive.

Always check whether the plan symbol covers the 3D model.

3.3 3D model

Make 3D models simple and fast. 3D models should not be more detailed then required. Put a 3D on/off switch in all objects to allow users to eliminate unwanted objects from the 3D view.

Keep in mind that the 3D model is used in 6 main contexts, these may require different look:

• 3D view
  Full detailed model. Inner details are of no interest.
• 2D projection
  Is used when the 3D model is projected to the 2D plan. Try to avoid projecting the 3D model to 2D because it slows down 2D regeneration (as 3D generation is needed for it).
• Sections
  Sections may display inner sturcture, which are unnecessary in 3D view.
• 3D editing feedback
  The editing feedback should be simplified for fast display preserving the main characteristics of the model.
• Preview in the Object Settings dialog
  Usually we use the full 3D model, in some cases it may be simplified.
• Operator for solid operation
  The operator-generating context can be used for an object which requires more space than its own volume. F.ex. a stair can generate cutting body for the space of the walking people when used to cut the floor slab of the upper storey.

Note that closed bodies regenerate faster in 3D than open ones (e.g., a cylinder is faster then an open tube).

3.4 User Interface tabpage

The Interface Script allows you to define your custom parameter-setting window. You can also add graphical and text type elements to help users in setting parameters. Use this function of ArchiCAD to make library elements user friendly.

Note that the available dialog size is 444 x 266 pixels. Don't use many (more than 7-9) tab pages - no one will find the one he needs.

The user interface tab pages should cover only the most important part of the whole parameter set since there's not much space there. This could mean some major dimensions or visualization styles which are hard to understand from the text-based parameter values.

Design a standard tabpage look and stick to it at positioning the dialog items - 'Previous' and 'Next' buttons, separators - for the ease of use.
See an example:

Since the Custom Settings pages of a GDL object cannot handle transparency in pictures or icons, use white background everywhere.

Please note that if an object has an Interface Script, the GDL Object Web Plug-in will display the UI window as the default parameter-setting dialog.

3.5 Comments

Since ArchiCAD 7.0 you can refer to a URL address from every object. The address of the referenced web page should be written in the first line of the Comment Window. If there's no web page defined there the default address will be displayed (http://www.graphisoft.com/gdlobjects). This a great possibility to provide online documentation for a library.

3.6 Preview Picture

Add preview pictures to all your library elements (including electrical symbols, macro objects) for smart library browsing.

Picture size has to be 128x128 pixels. Any other size will be displayed distorted in the library browser window. Keep in mind that the preview picture displays in 64x64 size in the object browser. It is reasonable to draw/generate the picture into 64x64 and then resize it to 128x128, so it will look fine in both views.

Previews have to show typical views of the elements, preferably from the same viewpoint and with the same neutral background. This helps to emphasize the characteristics of the objects. Axonometric or perspective images with wall or floor make the elements difficult to recognize.

4. Extra Requirements for Openings

Windows and doors are the most visualized libarary parts, their correct display is significant in every architectural drawing. That's why they need extra care in the design phase, too.
Let's list some relevant issues in connection with windows and doors.

2D and 3D representations of doors and windows have to be based on national and international standards (opening line, plan symbol in different scales, nominal opening, etc.).

Wall openings appear in section drawings, define the model clear for that case.

Doors and windows have to work in straight, trapeze and curved walls as well.

The result of rotating, mirroring and flipping must be specified for each window/door part distinctly (leaf/sash, frame, sill/treshold, trim, shutter, etc.).

Scale sensitive behaviour must be defined. At least 2-3 detail levels should be specified conforming the local standards, these may be a scale-independent option, too.

Decide whether to shroud the zone/slab fills under the window sill with a fill.