# Publications

From a high-level point of view, a publication, composed of a name, is a reference to an entity. This referenced entity can be geometry, topology, a feature, an attribute, or even an annotation. When several publications are defined, we call a publication set, which is the collection of all such publications.

HOOPS Exchange is able to retrieve the following referenced entities:

- Bodies, planes, and sketches;
- Geometrical lines and points;
- Faces, edges, and vertices.

When the referenced entity is not found, only the publication name is defined, and the reference is left empty. Finally, in an assembly, not all instances from the same model are referenced when one of them is referenced; i.e., it is possible to target a specific instance of a model.

## API Overview

Through the HOOPS Exchange API, a publication set is defined on the product occurrence which created it, as shown in the following structure:

    1typedef struct
    2{
    3   // ...
    4   A3DAsmPublicationSet* m_pPublicationSet;
    5} A3DAsmProductOccurrenceData;

If the publication set is null, then no publications are stored on the given product occurrence. Let’s see how to traverse a publication set.

Publication set

A `publication set` is structured as follows:

    1typedef struct
    2{
    3     A3DUns16                m_usStructSize;
    4     A3DUns32                m_uiPublicationsSize;
    5     A3DAsmPublication**     m_ppPublications;
    6} A3DAsmPublicationSetData;

The field `m_ppPublications` is an array of publications of size `m_uiPublicationsSize`.

To get the information from this structure, one needs to call `A3DAsmPublicationSetGet()` as shown in the following code:

     1A3DStatus traverse_publication_set(const A3DAsmPublicationSet* publication_set)
     2{
     3    if (!publication_set)
     4    {
     5        return A3D_SUCCESS;
     6    }
     7
     8    A3DAsmPublicationSetData publication_set_data = A3D_MAKE_DATA(A3DAsmPublicationSetData);
     9
    10    if (A3DAsmPublicationSetGet(publication_set, &publication_set_data) == A3D_SUCCESS)
    11    {
    12        for (unsigned int i = 0; i < publication_set_data.m_uiPublicationsSize; i++)
    13        {
    14            traverse_publication(publication_set_data.m_ppPublications[i]);
    15        }
    16
    17        A3DAsmPublicationSetGet(0, &publication_set_data);
    18
    19        return A3D_SUCCESS;
    20    }
    21
    22    return A3D_ERROR;
    23}

In the code above, the loop allows us to traverse all publications stored within a publication set. Let’s see how to traverse a publication.

Publication

A `publication` is structured as follows:

    1 typedef struct
    2 {
    3     A3DUns16                        m_usStructSize;
    4     A3DUns32                        m_uiLinkedItemsSize;
    5     A3DAsmPublicationLinkedItem**   m_ppLinkedItems;
    6 } A3DAsmPublicationData;

The field `m_ppLinkedItems` is an array of references to entities of size `m_uiLinkedItemsSize`. Regarding the publication name, it is not stored directly in this structure but in the root base of the publication.

To get the information from this structure, one needs to call `A3DAsmPublicationGet()` as shown in the following code:

     1A3DStatus traverse_publication(const A3DAsmPublication* publication)
     2{
     3    if (!publication)
     4    {
     5        return A3D_SUCCESS;
     6    }
     7
     8    // The name of the publication is stored in the root base.
     9    A3DRootBaseData root_base_data = A3D_MAKE_DATA(A3DRootBaseData);
    10    A3DRootBaseGet(publication, &root_base_data);
    11
    12    A3DAsmPublicationData publication_data = A3D_MAKE_DATA(A3DAsmPublicationData);
    13
    14    if (A3DAsmPublicationGet(publication, &publication_data) == A3D_SUCCESS)
    15    {
    16        for (unsigned int i = 0; i < publication_data.m_uiLinkedItemsSize; i++)
    17        {
    18            traverse_publication_linked_item(publication_data.m_ppLinkedItems[i]);
    19        }
    20
    21        A3DAsmPublicationGet(0, &publication_data);
    22
    23        return A3D_SUCCESS;
    24    }
    25
    26    A3DRootBaseGet(0, &root_base_data);
    27
    28    return A3D_ERROR;
    29}

In the code above, the publication name is retrieved from the root base, and the publication linked item is traversed. Let’s see how to traverse a publication linked item.

Publication linked item

A `publication linked item` is structured as follows:

    1 typedef struct
    2 {
    3     A3DUns16                    m_usStructSize;
    4     A3DAsmProductOccurrence*    m_pTargetProductOccurrence;
    5     A3DEntity*                  m_pReference;
    6 } A3DAsmPublicationLinkedItemData;

The field `m_pTargetProductOccurrence` corresponds to the product occurrence to which the referenced entity belongs; this is very useful in an assembly context. If the model is a part, this field is null as the targeted product occurrence would be the same as the one on which the publication is defined.

The field `m_pReference` is the referenced entity:

- If the referenced entity is not a topological item, then this field directly references an object whose type is defined in “Referenceable Non-Topological Entities.”
- Otherwise, if the referenced entity is a topological item, then this field is a `Reference On Topology Item`.

To get the type of the entity referenced by this field, one can call the `A3DAsmPublicationLinkedItemGet()` and `A3DEntityGetType()` functions as shown in the following code:

     1 A3DStatus traverse_publication_linked_item(const A3DAsmPublicationLinkedItem* publication_linked_item)
     2 {
     3     if (!publication_linked_item)
     4     {
     5         return A3D_SUCCESS;
     6     }
     7
     8     A3DAsmPublicationLinkedItemData publication_linked_item_data = A3D_MAKE_DATA(A3DAsmPublicationLinkedItemData);
     9
    10     if (A3DAsmPublicationLinkedItemGet(publication_linked_item, &publication_linked_item_data))
    11     {
    12         if (publication_linked_item_data.m_pTargetProductOccurrence)
    13         {
    14             // Do something with the target product occurrence.
    15         }
    16
    17         A3DEEntityType type = kA3DTypeUnknown;
    18         A3DEntityGetType(publication_linked_item_data.m_pReference, &type);
    19
    20         if (type == kA3DTypeMiscReferenceOnTopology)
    21         {
    22             // The referenced entity is a topological item.
    23
    24             return A3D_SUCCESS;
    25         }
    26
    27         // The referenced entity is not a topological item.
    28
    29         A3DAsmPublicationLinkedItemGet(0, &publication_linked_item_data);
    30
    31         return A3D_SUCCESS;
    32     }
    33
    34     return A3D_ERROR;
    35 }

In the code above, the targeted product occurrence can be traversed if it is not null. Then, the type of the referenced entity is retrieved to see if it is a Reference On Topology Item.

## Examples

Let’s see some publications with CATIA V5.

Publication of a body in a part

In the screenshot above, the publication “PartBody” references a body in “Part1”.

- As the publication is defined in a part, the publication set is defined in the product occurrence of the part.
- As the model is not an assembly, the targeted product occurrence is null, i.e., the referenced entity belongs to the product occurrence in which the publication has been created.
- As the referenced entity is not a topological item then the reference points directly on the body of the model.

Publication of a face in a part

In the screenshot above, the publication “Face” references a face from “PartBody” in “Part1”.

- As the publication is defined in a part, the publication set is defined in the product occurrence of the part.
- As the model is not an assembly, the targeted product occurrence is null, i.e., the referenced entity belongs to the product occurrence in which the publication has been created.
- As the referenced entity is a topological item, the reference is a Reference On Topology Item.

Publication of a body in an assembly

In the screenshot above, the publication “PartBody” references a body from “Part1” in “Product2”.

- As the publication is defined in an assembly, the publication set is defined in the product occurrence of the assembly node.
- As the model is an assembly, the targeted product occurrence is not null and references the product occurrence of the model to which the body belongs.
- As the referenced entity is not a topological item then the reference points directly on the body of the model.

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Exchange in your own language, or choose a sample question below to start a conversation:

What is HOOPS Exchange?
What are the latest release notes for HOOPS Exchange?
How do I start evaluating HOOPS Exchange?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...