External Parameter Definitions in Teigha BIM

Alexander Geniatov

October 19, 2017

Teigha BIM supports external parameter definitions, which are entities stored in external text files and not included in project/family documents but can be imported into documents. Parameter elements of the ParamElemExternal class store the guid of an external parameter definition.

External parameter definitions file structure

Here is a simple example of how these files look:

*META	VERSION	MINVERSION
META	2	1
*GROUP	ID	NAME
GROUP	1	1
GROUP	2	2
GROUP	3	Exported Parameters
*PARAM	GUID	NAME	DATATYPE	DATACATEGORY	GROUP	VISIBLE	DESCRIPTION	USERMODIFIABLE
PARAM	f5ff6402-9260-4e5a-9f8e-49d14a351e19	Area	AREA		3	1		1
PARAM	1f8f5e6f-f6e9-43a0-a059-d610dfd26402	Param11	TEXT		2	1	Desc1	1
PARAM	844695f1-a33f-40d7-aacf-a0e131d51a97	Param 2	FORCE		1	1	444	1
  • The META section corresponds to metadata, version 2 with minversion 2 files that are used in all modern versions of .rvt/.rfa files. Currently it’s the only version supported in Teigha BIM.
  • The Groups section represents groups of external parameter definitions; each group has a name and ID (both fields are unique). These groups have no relation to parameter groups or anything else in .rvt/.rfa documents and are used only for grouping external parameter definitions (for example, in the Shared parameters dialog).
  • The Params section contains external parameter definitions.

Each section begins with a header string starting with the “*” symbol and contains a list of fields in a section table. The fields in both headers and entity tables are separated with tab symbols.

External parameter definitions in Teigha BIM

All interfaces required for working with external parameter files are located in the Database/BmExtParamDef.h file. The file defines two classes:

  • OdBmExtParamDef — Represents external parameter definitions.
  • OdBmExtParamDefFile — Represents a file for storing external parameters and groups.

OdBmExtParamDef class

This class represents an external parameter definition, and its fields correspond to fields of entities in the PARAM section:

  • OdString m_name; — Name of parameter that goes to the caption field of OdBmParamDef.
  • OdBm::ParameterType m_dataType; — Parameter type that defines which child of OdBmParamDef will be used and the unitType for ParamDefValue.
  • OdInt64 m_dataCategory; — Defines the family type category (applicable for family type parameters only).
  • OdUInt32 m_groupId; — ID of the group that the parameter belongs to.
  • bool m_isVisible; — Visibility flag that corresponds to the IsUserVisible field of OdBmParamDef.
  • OdString m_description; — Description that goes to the description field of ParamElemExternal.

In addition to get and set methods, the class contains a method for creating a parameter definition that can be used for creation of database parameters (ParamElemExternal), i.e. to import an external definition to the database; the class also contains a constructor for creating an external definition with OdBmParamDef that exports parameters from the database to shared parameter files.

OdBmParamDefPtr getParamDef(const OdBmDatabasePtr& pDb) const;
OdBmExtParamDef(const OdBmParamDefPtr& pParamDef, OdUInt32 groupId, const OdString& description);

OdBmExtParamDefFile class

This class represents a database (file) of external parameter definitions and provides an interface for loading and saving the database from/to a stream and adding, removing, etc. parameter definitions and groups.

  • getGroups — Returns a group’s id-string name map as a constant ref.
  • addGroup — Adds a group. If a negative ID is passed, the interface allocates an ID itself and returns it.
  • deleteGroup — Deletes a group. A group can be deleted only if it doesn’t contain parameter definitions.
  • renameGroup — Renames a group.
  • isValidGroup — Validates whether a group with the passed ID is present in the database.
  • getParams — Returns the parameter definitions guid-OdBmExtParamDef map as a constant ref.
  • getParamsByGroup — Returns the map of the parameter definitions belonging to a group.
  • getParamByGUID — Returns the parameter definition by guid.
  • addParam — Adds a parameter definition to the database. Returns the error id with the param name if the guid is not unique or the datatype or group are invalid.
  • deleteParam — Deletes a parameter.
  • moveParam — Moves a parameter to another group.
  • getParamTypeByTag — Returns the ParameterType by string tag used in the DATACATEGORY field of the PARAM section records in the file (for example, the tag AREA corresponds to parameter type OdBm:: kPT_Area).
  • getParamTypeTag — ReturnsParameterType by string tag DATACATEGORY.
  • loadFromStream — Loads database content from the stream.
  • saveToStream — Saves database content to the stream.