4D sequence data source

4D sequence data source is a data source type which provides a sequence-based visualization for 3D objects in the model view. In essence, this works similarly to categorization-based visual styles, with time added in as a variable. Once configured, 4D sequences are found in the model view the same way as visual styles.

4D sequences are only available in eShare App.

Creating a 4D sequence data source

Create a 4D sequence data source to enable users to easily visualize progress and changes to objects in 3D view.

Prerequisites

The project contains a database adapter that can connect to the database that contains the sequence information. See Creating a database adapter if needed.

Do the following:

Navigate to the project to edit, and then click Project Admin in the main menu. The project administration view opens.
Click Adapters and Data Sources. The Adapters and Data Sources configuration view opens.
On the Adapters list, click the database adapter to which to add the data source.
In the adapter settings, click Add data source, select the data source type Database 4D Sequence Data Source, and then click Create data source.
In the Data Source section, specify the following settings:

Name – Enter a name for the data source.
Description (optional) – Enter a description for the data source.
State – Specify whether the data source is disabled or enabled (default).

In the Groups allowed to see the data section, select user groups that should be allowed to see the data that this data source provides.
- If no groups are selected, only administrators will see the data.
- Add user groups with Add.
- Remove user groups with the remove button.
- If the All Users group is selected, other group selections will be ignored.

The Adapter Configuration section is read-only.

Specify the Data Source Configuration settings:
- Excluded object visibility state – This setting defines what should happen to the visibility of model objects in the 4D sequence which do not have an initial category.
  - Do not change (default) – The visibility of any model objects without an initial category will not be changed.
  - Show all objects – Every single model object without an initial category is made visible automatically before starting the animation.
  - Hide all objects – Every single model object without an initial category will be automatically hidden before starting the animation.
- 4D step type – This setting defines what data type is used when determining the steps for the sequence.
  - Text – A string-based value from the database is used to determine the names of the steps, which need to be manually added and arranged in the configuration.
    If you select Text, see the following:
    Show/hide details
    Steps section contains a list of all steps that have been added to the configuration. You can use the input field and Add Step to manually add step names to the list. If one or multiple queries have been defined in the configuration, you can use Query for Steps to find steps by executing database queries defined in the configuration. All found steps can be seen in the drop-down menu below, and you can add steps to the step list by selecting them in the menu, or you can add all of them at once with Add All Found Steps button.
  - Time (default) – A datetime-based value from the database is used to generate the steps.
    If you select Time, specify the following:
    Show/hide details
    Step length – Sets the length of a single step in the 4D sequence. For example, setting the step length as "0 months, 1 days, 0 hours" means the length of each step is 1 day. Setting a low value in this field may result in very long 4D sequences.
    Start time – Sets the time from where the 4D sequence should start.
    From first (default) – 4D sequence starts from the earliest time that the defined queries find from the database.
    Specific start time – 4D sequence starts from the specified date picked with the calendar tool (with time 00:00, meaning that the selected day is included in the 4D sequence).
    Relative start time – 4D sequence starts relative from the time of the user executing the query. This is defined in months, days and hours, which can contain negative and positive numbers. Negative values indicate the past, and positive values indicate the future. For example, setting the relative start time as "-1 months, -14 days, 0 hours" means the start time would be 1 month and 14 days before the time of the query. 0 value in all the fields means the start time is the time of the query ("today").
    Note: Relative start time rounds the given values down: If hours are in use, after calculating the start time it is rounded down to the beginning of the hour (e.g. 1970-01-01 09:49 is rounded to 1970-01-01 09:00). Otherwise, the start time is rounded down to the beginning of the day (e.g. 1970-01-01 09:49 is rounded to 1970-01-01 00:00).
    End time – Sets the time when the 4D sequence should end.
    To last (default) – 4D sequence ends to the latest time that the defined queries find from the database.
    Specific end time – 4D sequence ends to the specified date picked with the calendar tool (with time 23:59, meaning that the selected day is included in the 4D sequence).
    Relative end time – 4D sequence ends relative from the time of the user executing the query. This is defined in months, days and hours, which can contain negative and positive numbers. Negative values indicate the past, and positive values indicate the future. For example, setting the relative end time as "-1 months, -14 days, 0 hours" means the end time would be 1 month and 14 days before the time of the query. 0 value in all the fields means the end time is the time of the query ("today").
    Note: Relative end time rounds the given values up: If hours are in use, the end time is rounded up the end of the hour (e.g. 1970-01-01 09:49 is rounded to 1970-01-01 09:59). Otherwise, the end time is rounded up the end of the day (e.g. 1970-01-01 09:49 is rounded to 1970-01-01 23:59:59).
    Time offset – Time offset adjusts the timestamps used for 4D sequencing. eShare assumes all received data uses UTC. If the data does not use UTC, specify the difference in the field in minutes. For example, if the timestamps in the database are saved in UTC+2, set the time offset to "-120".
    Note: If you set From first as start time and to last as end time, the animation will use all available data from the query. This may result in a very long and memory consuming animations.
- Conflict resolution – This setting specifies the behavior (coloring) of 3D model objects, which return multiple categories in the queries.
  - First Category (default) – The object will have the color of the first matching category (ie. topmost in the configuration).
  - Last Category – The object will have the color of the last matching category (ie. undermost in the configuration).
- Queries – In this section queries to fetch data from the database are defined. The configuration needs at least one query to be operational. Click Add query and define the tags and the database query to use:
  - In the Tags field, specify which tags in the model should match the query results. In the simplest case, the query returns values of a single tag.
    
    It is also possible to enter multiple tags as a comma-separated list, or use compound tags that combine the values of several tags.
    
    Do not use group tags in categorization. Instead, use the tag that the members of the group have. For example, use pli instead of [pli].
  - In the Query field, specify the SQL query to select the columns to be picked for the 4D sequence. Pick the columns in this order:
    - The value used for categorization
    - The time- or text-based value to determine which step the row belongs in
    - As many values as are needed for the Tags section.
    This is an SQL query that returns a number of rows, one row for each model entity for which a category is defined. The query should do a SELECT into the database and return the category as the first column, followed by a column for each tag that is needed to identify the model items.
- Categories – Create the categories that should be available to users in the 3D model viewer. You can create a new category manually (click Add category) or generate categories by running the database query (click Refresh).
  
  The Case sensitivity setting specifies if the value column in the defined categories is expected to be case-sensitive when matching the values to the found values. Case sensitivity does not affect fields that use ranges or regexes (they are always case sensitive).
  
  The Show to user setting specifies what categories are displayed to the user in the visual style drop-down menus.
  - If set to Listed categories, the user will only see the categories that are defined in this view.
  - If set to All categories, the system will create a category for each value that is not defined in this view, and the user will see both manually configured and automatically generated categories. Because these dynamic categories are created on-the-fly and not saved, the color that is assigned to them in visual style might change if the values change.
  Note: The categories and member counts here are for ALL the steps in the 4D sequence. All the categories are not necessarily in the same steps, but they are all shown and defined here.
Specify the settings of each category:
1. Value – The internal category name. This should match a value that the database query returns. Note that it is also possible that the query returns empty/undefined values.
2. Display Value – This is the name that the users see. If left empty, the Value field is shown to users instead.
  
  You can define a display name for categories for which the database query returns an empty value for Value field. By default their display name is [Empty], and also null values and values that only consist of white space are handled in the same way.
3. Color – If Visual Style is enabled, use the Color tool to pick an appropriate highlight color for categories returned by the query. All categories that are generated by running the query are set to red color by default.
4. Color Transparency – Set the color transparency of the color.
5. Members – Displays the number of matching items in the query result.
Example category configuration:

Note: If the model contains objects that have no matching tags or objects that do not exist in the database, they will be listed as Uncategorized in the model viewer.
You can drag the rows to specify the order in which the categories are to be listed in the model viewer, or click the delete button to delete a category that is not needed.
After defined queries have been executed at least once by selecting Refresh or Query for Steps, the Found 4D Sequencing Data is shown. The table has three columns displaying the 4D-related data found from the database.
- Found step – The name of the step found. These should be in the order of the animation (unless you change the configuration and do not execute the queries again). If the name is in cursive, the found step is NOT part of the 4D sequence.
- Number of categories – Tells the number of different categories that have a change in objects during this step.
- Number of objects – Tells the number of objects that change category during this step.
Click Save.

Multiple tags in categorization data sources

The database that a categorization data source connects to might contain different types of objects that use a variety of tags to store values that can be seen as belonging to the same category. For example, you might want to create a query that finds all objects that have any kind of position id. In this case, you must define multiple tags for the query, and an object will be included in a category if it has any of those tags and the value of the tag matches the category name.

In the Tags field, you define multiple tags by entering each tag on separate line.

For example, if the query is to be matched against the four commonly used position id tags, namely Valve Position (vpo), Instrument Position (ipo), Equipment Position (.n5), and Structural Position (.no), the Tags definition would be:

vpo
ipo
.n5
.no

A query that looks for multiple tags basically functions in the same way as a query that looks for a single tag in that the system compares the query results to each tag separately.

Compound tags in categorization data sources

Some objects in a 3D model cannot be uniquely identified by a single tag, and a combination of tags must be used instead. You can define a compound tag in the Tags field of a categorization data source by entering the required tags as a comma-separated list.

For example, piping spools created with CADMATIC Plant Modeller can be identified by the combination of Isometric Drawing Number (Idn) and Spool Number (spn), and the Tags definition would be:

Idn, spn

A compound tag should only contain tags that are needed to identify the object. All values that the database query returns must match the tag combination, and adding unnecessary tags can have a negative impact on system performance.

You can even include multiple compound tags in a single Tags definition. Each subset must be entered on a separate row and consist of the same number of individual tags.

For example, if the first compound tag is Idn, spn, any additional compound tags must consist of two tags as well. If we add a second compound tag that is based on Pipeline (pli) and Spool Number (spn), the Tags definition would be:

Idn, spn
pli, spn

When using compound tags, the database query needs to refer to one column per included tag, instead of just a single column.

For example, if Isometric Drawing Number (Idn) and Spool Number (spn) are used to form a compound tag, the query could be something like this:

Tags: Idn, spn

Query: SELECT Status, ModificationTime, DrawingNumber, SpoolNumber FROM SpoolTable