attributes

STANDARD ATTRIBUTES(5)    BRL-CAD Standard Conventions    STANDARD ATTRIBUTES(5)



NAME
       attributes - standard attribute conventions in BRL-CAD databases

BACKGROUND
       Starting with BRL-CAD database format version 5, BRL-CAD supports the
       storage of arbitrary attribute/value data on any database object. Prior
       to the development of this generic ability, BRL-CAD supported a set of
       standard attributes used to hold key information about specific
       properties. These conventions predate not only the version 5 database
       format but BRL-CAD itself. The purpose of this man page is to identify
       the standard attributes, document situations where two or more attributes
       are used to identify the same property, and identify where appropriate
       what constitutes meaningful values for an attribute.

       The earliest ancestor of BRL-CAD was the MAGIC code, written by the
       Mathematical Applications Group, Inc. in 1967 to implement geometric
       modeling ideas developed by BRL and AMSAA from 1958-1967. That system,
       which was entirely non-graphical, was followed some years later by the
       GIFT program—Geometric Information From Targets. LIBRT, appearing around
       1983, became the successor to GIFT. Today it is the core library of the
       BRL-CAD solid modeling package. (For more background see
       http://ftp.arl.army.mil/~mike/papers/96thebook/). LIBRT inherited both
       geometric primitives and attributes from GIFT--this heritage is
       occasionally apparent in attribute names.

       Note that with the introduction of support for arbitrary attribute/value
       pairs it becomes much simpler for both developers and users to formulate
       new standards of their own for storage of metadata in attributes.
       Attributes should only be documented in this file if one or more core
       BRL-CAD tools has implemented one or more features that require specific
       attributes to be present. Conventions for attribute names that do not
       involve tool support should be documented in appropriate user-level
       documentation. In documenting attributes, one additional distinction is
       made: attributes that exist only as post-v5 attribute/value pairs are
       referred to as non-core attributes; older attributes (which may also be
       represented in core data structures) are referred to as core attributes.

STANDARD (CORE) AND REGISTERED ATTRIBUTES
       The following table lists all known standard (core) BRL-CAD attributes
       and aliases. Any code setting or reading the value of one of these
       attributes must handle all aliases to ensure all functions asking for the
       value in question get a consistent answer.

       Table 1. Standard (Core) Attributes List
       ┌────────────┬─────────────┬───────────┬─────────────────┬─────────────┬─────────────┐
       │Property    Attribute   Is Binary Definition      Example     Aliases     │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Region Flag │ region      │ 0         │ boolean         │ Yes, R, 1,  │             │
       │            │             │           │                 │ 0           │             │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Region      │ region_id   │ 0         │ an integer      │ 0, -1, and  │ id          │
       │Identifier  │             │           │                 │ positive    │             │
       │Number      │             │           │                 │ integers    │             │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Material    │ material_id │ 0         │ zero or         │             │ giftmater,  │
       │Identifier  │             │           │ positive        │             │ mat         │
       │Number      │             │           │ integer         │             │             │
       │            │             │           │ (user-defined)  │             │             │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Air Code    │ aircode     │ 0         │ an integer      │ '0', '1',   │ air         │
       │            │             │           │ (application    │ or '-2'     │             │
       │            │             │           │ defined)        │             │             │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Line of     │ los         │ 0         │ an integer in   │ '24' or     │             │
       │Sight       │             │           │ the inclusive   │ '100'       │             │
       │Thickness   │             │           │ range: 0 to     │             │             │
       │Equivalence │             │           │ 100             │             │             │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Color       │ color       │ 0         │ a 3-tuple of    │ "0 255 255" │ rgb         │
       │            │             │           │ RGB values      │             │             │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Shader Name │ shader      │ 0         │ a string of     │             │ oshader     │
       │            │             │           │ shader          │             │             │
       │            │             │           │ characteristics │             │             │
       │            │             │           │ in a standard   │             │             │
       │            │             │           │ format          │             │             │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Inherit     │ inherit     │ 0         │ boolean         │ Yes, 1, 0   │             │
       │Properties  │             │           │                 │             │             │
       ├────────────┼─────────────┼───────────┼─────────────────┼─────────────┼─────────────┤
       │Time Stamp  │ mtime       │ 1         │ a binary time   │             │ timestamp,  │
       │            │             │           │ stamp for an    │             │ time_stamp, │
       │            │             │           │ object's last   │             │ modtime,    │
       │            │             │           │ mod time (the   │             │ mod_time,   │
       │            │             │           │ time is         │             │ mtime       │
       │            │             │           │ displayed in    │             │             │
       │            │             │           │ human-readable  │             │             │
       │            │             │           │ form with the   │             │             │
       │            │             │           │ 'attr' command) │             │             │
       └────────────┴─────────────┴───────────┴─────────────────┴─────────────┴─────────────┘





       Given the importance of these attributes, it is appropriate to briefly
       outline the meaning and purpose of each of them:

       region:
           The Region Flag identifies a particular geometric combination as
           being a solid material; in other words, any geometry below this
           combination in the tree can overlap without the overlap being
           regarded as a non-physical description, since it is the combination
           of all descriptions in the region object that defines the physical
           volume in space.

       region_id:
           The Region Identifier Number identifies a particular region with a
           unique number. This allows multiple region objects to be regarded as
           being the same type of region, without requiring that they be
           included in the same combination object.

       material_id:
           The Material ID Number corresponds to an entry in a DENSITIES table,
           usually contained in a text file. This table associates numbers with
           material names and density information used by analytical programs
           such as 'rtweight'.

       aircode:
           Any non-zero Air Code alerts the raytracer that the region in
           question is modeling air which is handled by specialized rules in
           LIBRT.

       los:

       color:

       shader:
           LIBRT can use a variety of shaders when rendering. This attribute
           holds a text string which corresponds to the name and other details
           of the shader to be used.

       inherit:
           The Inherit Properties value, if true, indicates all child objects
           inherit the attributes of this parent object.

       mtime:

SEE ALSO
       attr(n).

AUTHOR
       BRL-CAD Team

COPYRIGHT
       This software is Copyright (c) 2010-2019 United States Government as
       represented by the U.S. Army Research Laboratory.

BUG REPORTS
       Reports of bugs or problems should be submitted via electronic mail to
       devs@brlcad.org



BRL-CAD                            03/02/2021             STANDARD ATTRIBUTES(5)