The BOLTS library consists of several different components, processes and conventions and a number of precisely defined concepts. The purpose of this document is to specify them in detail.
In this section some concepts are defined, that will be used later in the specification of the blt-file.
A BOLTS repository contains a various sorts of data about objects, that are in some way useful in CAD. A part is an object that can be described by a set of parameters. E.g. a piece of paper is described by its width of 210mm and its height of 297mm.
However, one often encounters parts that are very similar to each other, for example just differing in their dimensions. These parts can then be more efficiently described as a class of parts. To continue with the paper example, a class describing pieces class could also contain a part with width 100mm and height 100mm.
In a blt-file only classes of parts are described, because this case is so frequent. Some parts are one of a kind, so it is not uncommon to have classes that contain just a single part.
The classes of technical parts that BOLTS deals with are often specified by standards issued by standardization bodies. This can be specified for a class in the blt-file. Within BOLTS, a class is referred to by its unique class id, but for the user a class may be known under multiple names or specified in multiple identical standards. To reflect this, classes can contain one or several class-name-element and class-standard-element constructs.
It turns out to be convenient to organize the classes of a BOLTS repository in collections. A collection usually has one or few authors, the parts contained are in some sense related to each other and all the data of a collection is under the same licence.
Each collection has a one word identifier, the collection id. The collection id is the filename (without extension) of the blt-file with the information about the collection, and also explicitly specified in the blt-file. For more details see there.
A BOLTS repository is directory structure with a certain layout. It contains all the data and metadata. The root directory contains at least a "data" directory with the backend independent data in blt-file, plus optionally a number of database directories with additional data that can be used by a backend. See list-of-databases for details.
A database directory is a directory that contains data about certain aspects of the parts or data in a specific form. Backends can access this data to transform the parts data into specific forms or collect informations.
In contrast to the data in the blt-file, the data in the database directories is optional. If for a class this data is not available, the backend has to be able to deal with it in an appropriate manner, for example by not processing this class.
In BOLTS the general, backend independent data and metadata is separated from the backend specific data for e.g. a particular CAD system. The former is held in blt-file, the latter in database directories.
A backend is a process that uses backend independent data and data from database, transforms this data and outputs a set of files. This output is called the distribution of this backend.
An example for a backend would be a process that uses the backend indepent data about parts, their geometries and dimensions together with a number of templates and stylesheets and produces a set of HTML pages with a nicely rendered, browsable description of the parts. Other backends could produce data that is suitable for use in specific CAD applications.
Backends are not specified in detail by this specification.
The backend independent data is stored in files with the extension .blt containing yaml markup. These files contain exactly one YAML document consisting of an associative array with the following keys:
The filename without the .blt extension is called the collection id. For consistency they are repeated in the id field. Collection ids are one word identifiers, which must be unique within the repository. They should contain only letters, numbers and underscores, and should be descriptive.
A class element is an associative array that holds information about a class. It has the following keys:
A class name element is a way to assign a name to a class. A class element should be used for general names, like "Hex head screws" and for names that are not derived from a standard issued by a standardisation body. For names that are derived from a standard, a class-standard-element is more appropriate.
A class name element is an associative array with the following keys:
The safe name of this class must be unique within the repository and provides a way to refer to this class.
A class standard element is similar to a class-name-element, but is used specifically to associate a class with a formal standard, and allows to expresses additional facts about this standard.
a class standard element is an associative array with the following keys:
If a group field is specified it has to be identical in all standards that belong to this group. In this case the standard fields have to contain a suffix or similar to distinguish them from the group, while still being unique. If several classes are specified in the same standard, the safe and nice names of the corresponding class standard elements must be the same in all classes. .. not sure I still understand this last sentence.
To be able to uniquely refer to class in different circumstances, it is necessary to have both a safe and a nice name. The former is used in file names or as function or variable name in a script, and therefore has to obey certain constraints. The latter is used in places, where no such constraints apply, like GUIs or web pages.
These two names are bundled up in a identifier-element, an associative array with the following keys:
One also wants to have name or labels for a part derived from a class. This name usually depends on the value of the parameters and, like with the identifier-element, must be available in a safe and nice form for use in different situations. The restrictions on the safe name are a bit weaker than with the identifier-element.
To insert the value of a parameter into this name, a placeholder of the form %(parameter)s can be inserted.
A parameter element is an associative array that holds information about the parameters of a part. This information is used when doing parameter-collection. Parameters are often dimensions, but are not restricted to be. The following keys are contained in a parameter element.
The two values of the type Bool are true and false (lowercase). Table index values (keys) are strings, and must be ASCII with no forward or backward slashes, no question marks, no asterisk, no colon, no pipe, no quotes, no lesser or greater than signs.
Tables of data are very common in standards and very useful for specifying a class of parts. A table element describes a table of values, where the row is specified by the value of an index parameter, and each column contains the value for a parameter. A table element is an associative array that has the following keys:
In some cases, a table-element is not powerful enough to represent the relationship between the values of free parameters and other parameters, for example if the value of a parameter depends on two free parameters at once. This case is covered by a table2d element. A table2d-element allows to lookup the value of the result parameter for a row given by a rowindex and a column given by a colindex.
A table2d element is an associative array with the following keys:
Parameter Collection is the process of assigning a value to each parameter. The set of all parameters is found by collecting parameter names from the fields of one or more parameter-element:
It is an error condition if there is a parameter name present as a key in the types field, that is not in the set of all parameters.
Then a value is assigned to each parameter. This can happen by:
It is an error condition if a parameter is not assigned a value or if there is more than one way to assign a value.
The parameter values collected in this way are for example used (among other things) to populate the template given in the substitution-element.
A base file element is an associative array containing informations about a file. Depending on the type of the file the contained keys are different. However, there are some keys that are present in every base file element:
Different data bases contain different base-file-types, for a list see list-of-base-file-types.
The drawings directory contains a number of subdirectories, one for each collection. In each of these directories, drawings of the parts can be stored, that illustrate the geometries of the parts and the meaning of the parameters.
In each directory there is a .base file with the same name as the directory. It contains metadata in form of a list of base-file-element of type "drawing-dimensions" or "drawing-connector" for the files in this directory. See base-file-type-drawing-dimensions and base-file-type-drawing-connectors.
The files containing all the informations necessary to build a geometrical representation of a class in OpenSCAD reside in the "openscad" directory. This database directory contains a folder for each collection which contains files related to this collection, and the folder is named like the collection-id.
One ingredient for this are base modules, OpenSCAD modules that take as parameters a subset of the parameters of the part (see parameter-collection), and construct the part according to these dimensions. These modules are stored in one or several files residing in the respective collection directory within the openscad database directory
In order to integrate the base modules properly, BOLTS needs informations about them. These informations are stored in the base-file of a collection, in form of one base-file-element of type "modules" (see base-file-type-module) for every file with one or more modules.
The "freecad" directory contains files that allow to build a geometrical representation of a class in FreeCAD. This directory contains a folder for each collection, containing the files related to classes in this collection.
The geometrical representation for a part is obtained from a python function that constructs the part using the scripting facilities of FreeCAD. The base-file contains a base-file-element of type "function" for every python module with one or more of these functions (see base-file-type-function).
The "solidworks" directory contains files necessary to build "design tables" for use with the SolidWorks software. The directory contains a folder for each collection with the files related to classes in this collection.
The geometrical representation of the parts is supplied in the form of parametrized models. Together with "design tables" these models allow to easily obtain different sizes and variations of a part.
This kind of base-file-element describes a drawing showing the dimensional parameters of a part. It is an associative array with the following keys:
This kind of base-file-element describes a file containing OpenSCAD modules. It is an associative array that contains the following keys:
A base module element is a associative array describing an OpenSCAD module with the following keys:
A base-module-cs describes a set of local coordinate systems or connectors that are attached to specific points of the part to allow easy positioning. This is implemented by a OpenSCAD function that returns a coordinate system structure. This function has all the arguments of the module in which the base-module-cs is contained, and an additional argument "location" as the last argument. A base-module-cs is an associative array with the following keys:
This kind of base-file-element describes a python file containing geometrical data in form of functions that build a part in a FreeCAD Document. It is an associative array with the following keys:
A base function element is a associative array describing a python function with the following keys:
This kind of base-file-element contains all the information necessary to create a design table that can be used together with a model file to create a "configuration". It is an associative array with the following keys:
A designtable class element specifies the classes that should be included in a designtable.
The license of a file contained in BOLTS must be one of the following:
where a + indicates a clause that allows a later version of the license to be used.