Decluttering your Digital Twin
The Life-Changing Magic of Grouping and Mapping
I am going to assume you are familiar with Marie Kondo, author, TV show host, and world-renowned tidying expert. Marie’s philosophy is to filter your belongings by what does and does not “spark joy” in your life. You can translate these principles over to how you handle your digital twins. I’d like to imagine that the contents of your digital twins spark joy into your lives, but I’ll be realistic and frame this conversation around functional and useful — what can you do to take your digital twins and extract only the most functional and useful content?
A digital twin can be highly detailed. Overkill level of detail. Most applications likely only need a tiny fraction of the data. We deviate slightly from the literal KonMari Method. Instead of discarding superfluous — non-joy-sparking — data we provide a framework to define what is important to you and extract only that information into a more usable format. But the end goal is the same — to optimize your experience whether it be in your life at home or when working with your digital twins.
Step 0 — Know your Tools
Decluttering a digital twin, like decluttering your physical home, is conceptually trivial but requires some thoughtful preparation. Let’s take a moment to acquire and familiarize ourselves with the tools for the job.
If you are entirely unfamiliar with iTwin.js our jump start should bring you up to speed.
To follow along with your own digital twin you need a running iTwin Viewer-based application. This guide will help if you don’t have one.
We will be leveraging the iTwin Reporting Platform APIs via the Grouping and Mapping widget. If you are new to widgets and UiProviders, go through this tutorial. Add the Grouping and Mapping widget to your viewer app.
Step 1 — Strategize
The first step to declutter a home is to decide on a categorization strategy. Thankfully with digital content, you don’t have to commit to a single categorization strategy, so we can spare you from any potential anxieties there. Start by identifying your goal. For example, calculating a breakdown of cost by material, and create a ‘Mapping’. Each Mapping for an iTwin represents a categorization of elements in the model.
When you launch your iTwin Viewer application with the Grouping and Mapping widget the first thing you should see is the Mappings view with a list of all Mappings created for the active iModel.
Another helpful way to think of Mapping is as a view of a model. Take for example a use case where you want to categorize elements by material. You may want a view of the model that is dedicated to analyzing material composition. Of course, don’t let the goofy Marie Kondo analogy or these examples limit your creativity. The entire framework of Grouping and Mapping is open-ended, flexible, and reusable. Categorize elements in your models however you see fit and reuse your categorizations for as many applications as you can.
Step 2 — Categorize
Mappings are an abstract container for the actual categories or ‘Groups’. Select a Mapping in the UI and you will find your Groups. If you want to categorize by material, your Groups might be Steel and Concrete. If you want to categorize elements to help with cost calculations, your Groups might be something like Slabs, Beams, Columns, and Walls.
I have only two rules: store all items of the same type in the same place and don’t scatter storage space.
— Marie Kondo
Quick technical talk. Each Group is defined by an ECSQL query. Developers experienced with the Bentley ecosystem are welcome to manually define Groups using the iTwin Reporting Platform APIs, but we recommend taking advantage of the UI-based approach of the Grouping and Mapping widget. It is far more accessible and extends the ability to create and define Groups to a much wider and less technical audience.
When creating a Group, use your cursor to select an element in the 3D view of your model. This will populate the ‘Group By’ section of the UI. This is where the magic happens. You will find a list with checkboxes of all relevant properties of the chosen element. Select one or more properties to build a filter that will define what elements belong in your Group. The 3D view will automatically update to reflect your choices.
The exercise of creating Groups effectively wraps two major decluttering steps into one — categorizing and filtering for what you find useful. Each Group in a Mapping represents a subset of elements in the model. And we only create Groups for what we care about. It isn’t mandatory to assign a Group to every element in the model. Two birds with one stone — I wonder if Marie Kondo would be proud? We can do better though.
Step 3 — Discard
So far, you have discarded elements you don’t care about by simply omitting them from the Group creation process, but we haven’t yet touched on the properties of the selected elements. You can take your decluttering effort a step further by only keeping the properties you care about.
Selecting a Group in the widget will take you to the Properties view. For now, focus on standard Properties — I’ll touch on Calculated Properties and Custom Calculations shortly. Whether or not any properties are added, by default, the following properties will always be extracted for every element:
- ECInstanceId
- ECClassId
- UserLabel
- BoundingBox Coordinates (High and Low)
All additional properties you wish to see in the extracted and decluttered data must be explicitly added. Reminder — focus on what is functional and useful to your objective. Let’s revisit the example scenario where you want to estimate material cost. For the Group consisting of Slabs, assuming they are Concrete Slabs, you would want to know the volume of concrete to be able to calculate an estimated cost. If the element already has a property for volume, great! Then you just need to define one property mapping for volume and carry on. If not, you may need to be a bit more creative. The product of length, width, and height can be used for rectangular volumes, so add all three.
Notice how properties can be mapped from a broad list of places. The technical background as to why there are so many and other details like what a TypeDefinition is are outside the scope of this article. Trust the widget to take care of you in that regard. All that you need to do is to go through the list and find what you need. In the example above, I found properties related to height from multiple sources and selected them. Selections can be ranked in order of preference. If the top choice is not available on a particular element we cascade down until we find a match.
Step 4 — Decorate
In the conventional KonMari Method we are now at the point where all our belongings have been categorized, pruned of items that do not speak to our hearts, and have started to put our homes back together. We have successfully categorized the contents of our digital twin into Groups, we have only taken the functional and useful elements into said Groups, and we have only taken the functional and useful properties. This is a non-trivial task, so now let’s reward ourselves and dress things up a bit.
Sorry, I don’t have cute containers and boxes for you to store your model elements in like Marie Kondo might have, but I can still offer something. In iTwin Reporting Platform speak, this something is a way to decorate the extracted data with additional useful information.
We skipped over Calculated Properties and Custom Calculations in Step 3. Calculated Properties are a set of built-in derived properties that you can use to augment your list of extracted properties. Suppose like in our earlier example you wanted to extract height for elements in a Group. In the example below, I use the ‘Longest Edge Length’ Calculated Property to generate a property I called ‘CalcHeight’ that hypothetically is missing in the source digital twin data.
Custom Calculations are like Calculated Properties in that they are also additional derived properties. You can write custom mathematical expressions using the values of available extracted properties to derive new properties. For example, earlier we discussed deriving volume from length, width, and height. This can easily be achieved using Custom Calculations with the formula: Length * Width * CalcHeight. Yes, you can use Calculated Properties in your formulas.
Step 5 — Apply
That’s it. Digital twin decluttered. Now take what you created and apply it to build something useful. A fantastic example of how you can leverage Grouping and Mapping to take advantage of a decluttered view of your digital twin has already been covered in another article, Automate your Digital Twin, by Johannes Renner. Johannes takes what we’ve done and builds a dashboard using Power BI to visualize data in a custom report.
Once a Mapping is defined, the data from your digital twin can be extracted and exposed through a set of OData compliant APIs. Any application you create can take advantage of these public APIs. If you already have a solution built on the iTwin Platform that doesn’t need a live connection to the full, unfiltered, cumbersome, and unsanitized model, this might be a great way to optimize your workflows.
Marie’s tidying process is not about decluttering your house or making it look neat on the spur of the moment for visitors. It’s about tidying up in a way that will spark joy in your life and change it forever.
The greatest thing about all this is that once you’ve gone through the process once, you can reuse the extracted view of your digital twin wherever it is needed. You can even copy Mappings between models to avoid going through the decluttering exercise more than once. Marie Kondo strongly emphasizes avoiding half-measures. Do it once and do it right. “It’s about tidying up [your digital twins] in a way that will spark [a fresh perspective into your workflows] and change [them] forever.“
