DirectShape Concepts

A DirectShape element is a container for an external custom geometry that can be created as a result of:

• Importing from other CAD formats.
• Storing geometry created with the BrepBuilder.

BimRv SDK implements DirectShape functionality through the following classes:

1. OdBmDirectShapeType is the class that provides an interface for storage of common information about DirectShape objects of the same type:
   • Common geometry that is inherited by all DirectShape elements of this type (setGeometryData(), setShape(), appendShape() methods).
   • View-specific geometry data (the method setPlanViewGeometryData())
   • Category of the element (setCategoryId() method).
   • DirectShape data validation checking result (isValidShape() methods).
2. OdBmDirectShape is the class that implements the functionality of working with DirectShape data. For creating a new DirectShape element, use the static method createElement() that returns a smart pointer to the created DirectShape element. Another way for creating a new DirectShape object with predefined type, category and transformation matrix that defines its position is to call the createElementInstance() from a smart pointer returned by the createElement(). This method retrieves identifiers for type, category and an instance of the transformation matrix.

   The type of the DirectShape element can also be specified with the setTypeId() method. Like the OdBmDirectShapeType class, this class also contains methods for setting and validating geometry data: setShape(), appendShape(), isValidGeometry() and isValidShape().

   For setting additional options for a DirectShape element, use the setOptions() method.

3. OdBmDirectShapeOptions is the class that allows to store and apply to a DirectShape element two options:
   • Referencing option that determines whether the element can be referenced. The element can be referenceable or non referenceable. Possible values of this option are represented with the DirectShapeReferencingOption enumeration(0 - NonReferenceable, 1 - Referenceable).
   • Bounding Room option that defines whether the element geometry can be used as a boundaries for a space occupied by the object. Possible values of this option are represented with the DirectShapeRoomBoundingOption enumeration(0 - NotApplicable, 1 - SetByParameter).
4. The OdBmDirectShapeDataCell class stores metadata of the DirectShape element such as:
   • Name.
   • Creating application global unique identifier (GUID) and specific application data GUID.
   • Identifier of the category object assigned with the DirectShape element.
5. The OdBmDirectShapeCell class is used for storage of geometry information represented with an instance of the OdBmGElement class. To get geometry information, use the getGElement() method, to set new geometry to the element, call the setGElement() method.

Creating a Simple DirectShape Element

It is assumed in the code fragments below that the following variables are defined:

• pDb — A smart pointer to a BimRv database.
• nodes — An array of geometrical nodes that represents the element geometry.

The following step-by-step instruction illustrate how a simple DirectShape element can be created with a specific set of options:

1. Create a new instance of the OdBmDirectShape class and add it to the database:

   
   OdBmDirectShapePtr directShape = OdBmDirectShape::createObject();
   OdBmObjectId retId = pDb->addElement(directShape);
           

2. The addElement() returns an identifier of the added object that can be used for checking the result of the operation. If the element was successfully added to the database, assign it with a family that owns it:

   
   OdBmGNodePtrArray nodes;
   if (!retId.isNull())
   {
     directShape->setOwningElementId(pDb->getOwnerFamilyId());
     directShape->setShape(nodes);
   }
           

   Call the setShape() method to create shape from the array of geometrical nodes. You can analyze the result of setting shape data through checking the value of the OdResult data type that the method returns.

For additional illustration of the process of creating the array of geometrical nodes, please refer to the sample command "BmBrepMeshCmd" that can be found in the TB_Commands sample application allocated in the BimRv/Examples/TB_Commands folder. The _BmBrepMesh_func() function that implements custom user command sequentally calls two functions, which are responsible for creating geometry data:

• createMeshOfGeometry().
• createBrepOfMesh().

All the functions are defined in the BmBrepMeshCmd.cpp source code file.

Creating a Complicated DirectShape Element

The following example source code illustrates creating a new DirectShape element, setting its parameters and applies graphical style to it.

Example assumes that there are two previously declared and defined variables:

• OdBmDatabasePtr& pDb; — Contains a smart pointer to a BimRv database that contains created DirectShape element.
• OdInt32 nColor; — Contains DirectShape element color value.

Besides it is assumed that a special structure, needed for encapsulated storing both category and graphical style identifiers for a new DirectShape element, is declared as well:

struct TCategoryIdAndGStyleId
{
  OdBmObjectId nGStyleElem;
  OdBmObjectId nCategoryElem;
};
    

The last prerequisite is the materialId variable that stores the element material identifier. The description of material element creation is omitted to make the code example simpler.

1. Create category element and graphical style elements (both are empty ones):

   
   TCategoryIdAndGStyleId aElements;
   aElements.nCategoryElem = pDb->addElement(OdBmCategoryElem::createObject());
   aElements.nGStyleElem = pDb->addElement(OdBmGStyleElem::createObject());
           

2. Get the identifier of the family-owner of the DirectShape element, generate material element and define three-dimensional extents for the geometry:

   
   OdBmObjectId oRootFamilyId = pDb->getOwnerFamilyId();
   OdBmObjectId materialId;
   OdGeExtents3d oBBox;
           

3. Create a DirectShape type instance and add it to the BimRv database:

   
   OdBmDirectShapeTypePtr pDirectShapeType = OdBmDirectShapeType::createObject();
   OdBmObjectId directShapeTypeId = pDb->addElement(pDirectShapeType);
           

4. Open previously create category element and set identifiers for its owning element and family:

   
   OdBmCategoryElemPtr pCategoryElem = aElements.nCategoryElem.safeOpenObject();
   pCategoryElem->setOwningElementId(oRootFamilyId);
   pCategoryElem->setFamId(oRootFamilyId);
   // DesignOptionId. Header has -1 value but body has -4 value
   pCategoryElem->setBaseDesignOptionId(pDb->getObjectId(-4));
           

5. Create an instance of category and associate it with the category element:

   
   OdBmCategoryPtr pCategory = OdBmCategory::createObject();
   pCategory->setName("New_Category");
   pCategory->setParentCategoryHandle(OdDbHandle(OdBm::BuiltInCategory::OST_GenericModel));
   pCategory->setCategoryType(OdBm::CategoryType::Model);
   pCategoryElem->setCategory(pCategory);
           

6. Set graphical styles for the category element:

   
   OdBmObjectIdArray aGStyleIds;
   aGStyleIds.push_back(aElements.nGStyleElem);
   pCategoryElem->setGStyleIds(aGStyleIds);
           

7. Assign the DirectShape type object with the style element:

   
   OdBmGStyleElemPtr pGStyleElem = aElements.nGStyleElem.safeOpenObject();
   pGStyleElem->setOwningElementId(directShapeTypeId);
   pGStyleElem->setOwnerId(directShapeTypeId);
   pGStyleElem->setFamId(oRootFamilyId);
   // DesignOptionId. Header has -1 value but body has -4 value
   pGStyleElem->setBaseDesignOptionId(pDb->getObjectId(-4));
           

8. Create a new style and incorporate it in the previously created style element:

   
   OdBmGStylePtr pGStyle = OdBmGStyle::createObject();
   pGStyle->setPenNumber(1);
   OdBmCmColor oColor;
   oColor.setRGB(nColor);
   pGStyle->setColor(oColor);
   pGStyle->setLinePatternId(pDb->getObjectId(-3000010));  // solid line
   pGStyle->setMaterialElemId(materialId);
   pGStyleElem->setGStyle(pGStyle);
   pGStyleElem->setGStyleType(1);
   pGStyleElem->setGStyleCategoryId(aElements.nCategoryElem);
           

9. Set the category tracking:

   
   OdBmCategoryTrackingPtr pCatTracking = pDb->getAppInfo(OdBm::ManagerType::CategoryTracking);
   pCatTracking->addCategoryDataItem(pDb->getObjectId(pCategory->getParentCategoryHandle()), aElements.nCategoryElem);
   pGStyle = aElements.nGStyleElem.safeOpenObject();
   pCatTracking->addGStyleDataItem(aElements.nCategoryElem, aElements.nGStyleElem, pGStyleElem->getGStyleType());
           

10. Create a new DirectShape object, set its properties and add it to the database:

    
    OdGeMatrix3d oTrf = OdGeMatrix3d::kIdentity;
    oTrf.setTranslation(OdGeVector3d(-30.0, 0.0, 0.0));
    OdGeExtents3d oBBoxTransformed = oBBox;
    oBBoxTransformed.transformBy(oTrf);
    OdBmObjectId directShapeId;
    OdBmDirectShapePtr pDirectShape = OdBmDirectShape::createObject();
    pDirectShape->setParam(pDb->getObjectId(OdBm::BuiltInParameter::PROJECT_ORGANIZATION_NAME), L"Open Design Alliance");
    pDirectShape->setParam(pDb->getObjectId(OdBm::BuiltInParameter::IS_VISIBLE_PARAM), (OdInt32)1);
    directShapeId = pDb->addElement(pDirectShape);
    pDirectShape->createElementInstance(directShapeId, aElements.nCategoryElem, oTrf);
            

For additional information about working with DirectShape element, please see the Creating a "Dummy" Element sample application located in the /BimRv/Examples/TB_ExCreateDummyObject folder.

See Also

How to Filter Elements

Work with Faceted Topology