3DDX import & export

3DDX is a Cadmatic format for exchanging CAD data, including the 3D models and attribute information, with various third-party CAD applications. Plant Modeller can export and import 3DDX data.

Importing model objects from 3DDX

3DDX files can be imported using the 3D-Import Manager tool, as described in 3D-Import Manager.

Model object import requires a license for 3DDX export and import.

Creating 3DDX export settings

The "3DDX Export Settings" configuration object defines the contents of the 3DDX file to export.

Typically, the 3DDX file should contain a subset of the 3D objects that are included in the Plant Modeller area. The desired subset can be, for example, all the objects that belong to a specific System or Group, or have a specific attribute or attribute value.

In this example, we create a template 3DDX Export Settings object and then use a script to generate multiple export settings—one per System.

Prerequisites

  • Model Query that defines the objects to include in the 3DDX export. See Queries.

  • 3D Publishing Control that defines the object attributes to include in the 3DDX export. See 3D publishing control.

Do the following:

  1. In the Project Environment dialog, go to [project] > 3D Export Settings > 3DDX Export Settings, and create a new 3DDX Export Settings object. In this example we name it as "3DDX Export Template".

    In the settings dialog, which is described in 3DDX export settings, select a Model Query that selects the 3D objects and a Publishing Control that selects the metadata (object attributes) that you want to export, and set the other settings as appropriate.

    Note: For information on including service spaces in the export, see Exporting service spaces to 3DDX.

  2. Create a new 3DDX export that uses the 3DDX Export Settings object, as described in Exporting model objects to 3DDX, and then perform the export once.

    Tip: You can open the exported 3DDX file in a text editor and verify that the required tags were published into the file.

  3. Use a script to generate a separate Model Query and a 3DDX Export Settings object for each System.

    1. In Plant Modeller, on the Tools tab, click Script and run the script file PMS_HOME/dm/macro/Create3DDXExportSettingsBySystem.mac.

    2. In the Select 3DDX object… dialog, select the template 3DDX Export Settings object and click OK.

    3. In the Select system to generate… dialog, select the Systems for which to generate a separate model query and click OK.

    4. When the process completes, a log file opens. Review the log to see if there was anything unexpected.

  4. In the Project Environment dialog, [project] > Model Queries now contains the generated System-specific queries, and [project] > 3D Export Settings > 3DDX Export Settings contains the System-specific export settings that you can select to use in a 3DDX export.

Exporting model objects to 3DDX

The project administrator can use integration software via the CADMATIC Web API or configure a Plant Modeller Service Instance to automatically export objects from the Plant Modeller 3D model.

For information on how to export 3DDX with CADMATIC Web API, see the help system of your CADMATIC Web API installation, or open the help from the CADMATIC Documentation Portal.

For information on how to export 3DDX with a Plant Modeller Service Instance, see the instructions below.

Prerequisites

Do the following:

  1. In the CADMATIC desktop, select Object > Manage Plant Modeller Services & Instances. Select the service to connect to, then select the instance to edit and click Edit Settings.

  2. In the Plant Modeller Service Instance Settings dialog box, open the Exports tab. For a detailed description of this tab, see Exports tab.

  3. Right-click the Scheduled exports pane and select New 3DDX Export from the context menu.

    The Select Export Configuration window opens.

  4. Select the 3DDX Export Settings object that defines what objects and object metadata to export, and click OK. The Edit Export Settings dialog opens.

  5. Define the export settings:

    • Schedule type – Define a suitable time for the export.

    • To – Select the output folder and define the name of the .3ddx file.

    • Export only changed templates, keep export history – Select this option if you want the export to include only those geometries that have changed after the previous export.

    • Force instance modification time to be updated when a change in its attributes has been found – Select this option if you want the export to track whether the attributes of the geometries have changed and to update the modification time if they have. (Plant Modeller does not update the modification time of an object if only the attributes have changed.)

      Note: The history information for these options is stored in the Service's workspace folder, in the export-specific file <NameOfExportConfiguration>.his. In this file, "arc" is the checksum for changes in the geometry and "mot" is the checksum for changes in the attributes.

    Then click OK. The 3DDX export is now scheduled to occur at the specified time.

  6. You can run the export also between the scheduled times by right-clicking the export and selecting Export now from the context menu.

  7. You can edit the export settings by right-clicking the export and selecting Edit from the context menu.

    In this editing context the names of the export options are:

    • Export only changed templates

    • Force modification time to follow changes in attributes for instances

  8. You can clear the export history and thus force complete re-export by right-clicking the export and selecting Reset export history from the context menu.

  9. Click OK to close the service instance configuration.

Exporting service spaces to 3DDX

In the 3D model, 3D Space objects whose type is "Service Space" can be associated with specific model objects.

In the 3DDX Export Settings dialog, the Model Query setting specifies which model query to use to select objects for 3DDX export.

When defining the model query, be aware of the following:

  • The model query selects the model objects to be exported.

  • If the model query selects model objects but not service spaces, selecting the option Export Service Spaces allows those service spaces that are linked to exported model objects also to be exported.

  • If the model query selects service spaces, they are exported even if they are not linked to model objects.

In the 3DDX file, service spaces are identified by the tag ".lu" having the value "12", and if the service space is linked to a model object, the object ID of the model object is defined in the tag "ASO".

Creating 3DDX library export settings

Library export for 3DDX requires the administrator to create a COS configuration object of type "User Data" which defines the scope of the export. This configuration is a text file that lists one or more Plant Modeller tags, and a library part is exported if it has any of those tags (attributes), even if the tag does not have a value in the given part.

The program searches the object hierarchy of the library parts in the following order, and if any of the specified tags are found at one of these levels, the object is exported, and each tag's value is taken from the first hierarchy level where the tag is found:

  • if the part is a GDL for Equipment, the tags are searched in this order:

    1. parametric model

    2. GDL

  • if the part is a Catalog Part, the tags are searched in this order:

    1. part size

    2. catalog part

    3. dimension table

    4. GDL (if it exists)

For general information on the User Data object, see User data.

Do the following:

  1. In the Project Environment dialog, browse to [library] > Resources > User Data.

  2. Select New > User Data.

  3. Enter a descriptive name for the User Data object and click OK.

  4. Right-click the new User Data object and select Edit from the context menu. The Edit Text dialog opens.

  5. In the first row, enter the text LIBRARY EXPORT.

  6. In the second row, define a data record that defines what to export:

    tgs <tag1> <tag2> ... <tagn>;spc 0|1;;

    • tgs – A space-separated list of Plant Modeller tags to consider. You can also leave this empty to include all tags.

    • spc – Set this to 0 to not export Service Spaces (this is the default) or 1 to export them.

    Copy 
    LIBRARY EXPORT
    tgs maf =0F;spc 1;;

     

  7. Click OK.

Exporting library data to 3DDX

Administrator can configure a Plant Modeller Service Instance to automatically export a 3DDX file with related STEP files that contain template data for GDLs (Equipment) or Catalog Parts.

After the first export, subsequent exports are incremental. You can force complete re-export by clearing the export history.

Prerequisites

Do the following:

  1. In the CADMATIC desktop, select Object > Manage Plant Modeller Services & Instances. Select the service to connect to, then select the instance to edit and click Edit Settings.

  2. In the Plant Modeller Service Instance Settings dialog box, open the Exports tab. For a detailed description of this tab, see Exports tab.

  3. Right-click the Scheduled exports pane and select New Library Export 3DDX from the context menu.

    The Select Export Configuration dialog opens.

  4. Select the "User Data" object that defines which tags an object can have to be included in the export, and click OK. The Edit Export Settings dialog opens.

  5. Define the settings:

    • Schedule type – Define a suitable time for the export.

    • To – Select the output folder and define the name of the .3ddx file.

    Then click OK. The 3DDX library export is now scheduled to occur at the specified time.

  6. You can run the export also between the scheduled times by right-clicking the export and selecting Export now from the context menu.

  7. You can clear the export history and thus force complete re-export by right-clicking the export and selecting Reset export history from the context menu.

  8. Click OK to close the service instance configuration.

About the CADMATIC 3DDX format

The CADMATIC 3DDX format uses a STEP file to define a 3D geometry and an additional tag file to publish the 3D object metadata. This format can be utilized in software integrations that require 3D geometries to be exported from CADMATIC and imported to some other 3D software. 3DDX export creates the following files:

  • <export's name>.3ddx – The 3DDX file, which lists the other entities included in the export.
  • *.stp – STEP files that define the geometry of the entities referenced from the 3DDX file.
  • <export's name>_conversion.log – The export log.
  • imp_<export's name>.req – Generated trigger file for waking up the Adapter and telling it to import the 3DDX file with the STEP geometries.

In the 3DDX file, the basic sections are:

  • Header – Starts with "H".
  • Templates – Each template starts with "T".
  • Template instantiation – Each instance starts with "C".

These sections are described in more detail below.

Header

The syntax of the header definition is "H" followed by a tag record. The tag record consists of tag fields (pairs of tag name–tag value) separated with semicolons. The record ends with an empty tag field.

The first tag "3DDXType" is not currently used. The other tags in the header list all COS attributes of the 3DDX Export Settings object which was used for generating the 3DDX file. This includes the COS references of the Model Query object and the 3D Publishing Control object.

COS_Schema: name of COS schema

COS_Server: name of COS server

Templates

A template definition starts with "T" and ends with "#". Geometry is defined only via templates. There are no "inline" definitions like there are for 3DD files. Templates are stored on import into COS as template objects.

The first line of a template consists of "T" and the globally unique identifier of the template. It is followed by a tag record which lists the following:

mot: modification time

prv: private or shared geometry

  • 1: private geometry, stored in the model object (for example, when object uses instance parameters or has been imported from 3DD to CADMATIC)
  • 0: shared geometry, stored in GDL

dbn: name of database where the geometry (such as equipment GDL, catalog part, or specific model object instance) is stored

.k5 etc: nodes. The format is the same as for nodes in 3DD files—see T for component template for details.

After the tag record there is the number of 3D primitives as an integer number; for the current version of 3DDX it is always 1.

The last line of a template definition is a reference to a STEP file. Application protocols AP 214 and 203 are supported, as they are supported by Open Cascade Technology which is used to read/write STEP files in CADMATIC.

Instances of Templates

A template instance definition starts with "C" and ends with "#".

"C" is first followed by the reference to the template, and then by a set of numbers:

  • x, y, z: local origin of the component
  • x_dx, x_dy, x_dz: local x-direction of the component
  • y_dx, y_dy, y_dz: local y-direction of the component

Then, there is a tag record that lists the published metadata.

"obi" is expected to store the writer-side unique identifier of the instance.

Note: Unlike 3DD, 3DDX does not support "inline"—all instances in a 3DDX file reference a template.

Importing

Import of 3DDX files is performed using either the 3D-Import Manager tool of Plant Modeller (see 3D-Import Manager) or Plant Modeller Service Instance.

In CADMATIC, the name of an import file defines an import context. The logical context must remain the same during the project, but the physical content of the context can be updated. 3D-Import Manager maintains import groups per import context—objects imported from a specific import file are assigned to the same import group.

During import, the templates in 3DDX files are converted into the CADMATIC format and stored into COS as "Import Template" objects. In contrast, 3DD files use templates only locally, when processing the 3DD file.

Templates and instances can update independently, that is, in the same or different 3DDX files. An instance in a 3DDX can reference a template which is not present in the same import file, if the template has been imported earlier.

Import supports nodes. The code must map to a valid existing definition in the current CADMATIC setup.

On import the objects can be processed based on import options (see 3D-import options):

  • Define the System to target the new instance.
  • Map metadata item to an existing CADMATIC attribute, and assign the metadata value as the attribute value.

Re-Importing

When 3D-Import Manager is re-importing a model object from the import file, the following occurs:

  • If the object is not present in the import group of this import context, then it is created as new.
  • If the object is present in the import group but is different compared to the one in 3D model, the object content in the 3D model is changed, but the object identity stays.

If an object exists in the 3D model as a member of the present import group, but is missing from the re-imported file, then the object is deleted from the model. This is how the system works also when 3DD files are re-imported.

3DDX file templates and instances are processed in the same way with the following exceptions:

  • Templates can be imported without instances in the same import file.
  • An instance can only be created if the template is defined in the same file or the template object already exists in COS.
  • Re-import never deletes existing Import Template objects.

Exporting

In CADMATIC, a 3DDX Export Settings object defines an export context. The logical context must remain the same during the project, but the physical content of the context can be updated.

During export, CADMATIC always writes all templates referenced by the instances to the 3DDX file. If several 3D objects use the same part data, then in the 3DDX file they reference the common template (corresponds with part data). As an exception, 3D objects which are created so that one or more of their dimensions (such as length of pipe) are defined at creation time by the designer, always generate an individual template.

Export supports nodes.

3DDX files are exported using export rules of the "3DDX Export Settings" object in COS:

  • Selection of model objects to export references a Model Query object to do the selection.
  • Selection of metadata to publish references a 3D Publishing Control object to do the selection.
  • Geometry generation options (Dump nodes, and so on).

All attributes of the used 3DDX Export Settings object are dumped as metadata to the header section of the exported 3DDX file.

Re-Exporting

A single exported 3DDX file fully defines the content of this export context at the write time in the CADMATIC 3D model and library databases.

All existing instances of the context are present. All templates of the instances are present. The last modification time in CADMATIC is provided via the tag "mot" for instances and templates separately.

It is up to the receiving system to implement delta management with this information.

Related Topics

Set detail info