Make the visualised state of data results more explicit in the UI

[abey79]

Consider this view (adapted from the arkit example):

The blueprint tree shows a whole bunch of data results: /description and all the /world/annotations/box-… ones.

The latter appear because they contain a Text component, which is visualisable in the text view:

Why, then, only the /description data result is being displayed? The full story about this is involved, but boils down to: "visualisers for the box... entities have not been automatically created, because these entities do not have a TextDocumentIndicator logged (or, in the future, a TextDocument archetype tag)".

Background

The determination of a view's content is akin to a funnel:

1. The starting point is the entities present in the store on the current timeline and at the current timepoint.
2. The entity path filter is then applied, which produces a possibly reduced set of candidate entities. (This is what the "Matches 16 entities" note in the first screenshot refers to.)
3. Then, applicability is determined, and only applicable entities are kept. An entity is applicable for a given view type if it contains at least all the required components for at least one the the archetype visualisers of that view type. In the case of the text view, the only required component of the only visualiser is Text.
   • in some cases there's also additional criteria on the data like is_vector for tensordata in the bar chart
4. The applicable entities are then filtered for "visualizability". Each view class is allowed to decide which entity are visualizer entities based on arbitrary view realted criterions. This is very rarely used. One example is the spatial view which will ignore objects which are under a double projections from it's pov. Entities that are visualisable and applicable become data result and are displayed in the blueprint tree. In the text view above, there is no applicability filter, and the screenshot shows the 8 visualisable (and thus applicable) entities.
5. Finally, each of the visualisable entities which also contains a matching indicator component is deemed an indicated entity. By default, the viewer spawns visualisers only for indicated entities. In the case of the screenshot above, only the /description entity is indicated, which explains why it is the only one that is displayed.

Notes:

• Visualiser can be created and deleted manually. So the actual set of visible entities in a given view can be an arbitrary subset of applicable entities. Only the default set of visible entities corresponds to the indicated entities. For the purpose of this issue, let's call the set of entities for which a visualiser is active the displayed entities (but we must find something else for the UI).
• Implementation-wise, i'm not 100% sure of the sequencing between steps (3) and (4), but that's beneath the point of this issue.

Problem

Absolutely NONE of the above is made particularly explicit in the UI. Surely we don't need to bubble that much details/complexity, but some consequence of this complexity is visible, and occasionally confusing (even for us!)

Suggestion

Sparingly provide more information on the above, trying to reach a balance between "too many details" and "what the heck is going on here".

For example:

• Non-displayed data result should be highlighted as such in the blueprint tree (clicking on them is the right first step to create a visualiser).
• The view selection panel should provide more information on the above pipeline, e.g.: "16 entities matched, of which 8 are visualisable, of which 1 is displayed"
• Come up with proper naming for all of this...

[nikolausWest]

I would have not included the non visualized entities at all. We don't really teach users about the data results concept and I don't think we have to. I think it's hard to ask the users to generally have a deeper mental model here other than something like "the blueprint tree shows whats in the viewport". Non visualized entities in data results feels like an intermediate result that users don't need to see.

I may be missing something central here though ofc

[abey79]

I would have not included the non visualized entities at all. We don't really teach users about the data results concept and I don't think we have to. I think it's hard to ask the users to generally have a deeper mental model here other than something like "the blueprint tree shows whats in the viewport". Non visualized entities in data results feels like an intermediate result that users don't need to see.

I may be missing something central here though ofc

I agree. I have laid out the full thing above for reference. I didn't mean we should make it all explicit. The core suggestion is to make it more explicit whether a data result (whether it's called that or not) is being displayed or not. My suggestions are basically steps in that direction.

Bascally I want to better answer two questions:

• My filter is + /**, why does my view have less entities that the streams tree?
• My view "contains" 10 entities in the blueprint tree, why do I only see 3 things in the view itself?

[Wumpf]

I would have not included the non visualized entities at all.

The big issue with that is that if for whatever reason a thing doesn't get a visualizer you won't be able to add it. Reasons why a thing doesn't have a visualizer when it could have one (i.e. is "visualizable"):

• lack of indicator (tag in the future)
• override of picked visualizer (either via api or blueprint)
• default picked by the view (that's really only just the transform arrows today: we don't show them in a buch of places even though we could, i.e. it's a per-viewer per-visualizer heuristic - normally the heuristic says "I show things if I find my indicator", but it's adjustable per view class)