Parenting entities makes _children[] of parent dirty

CesiumJS
6

The parent/children of an entity are not intended for modeling domain- or application-specific hierarchies. I even hesitated to suggest setting parent=undefined, and emphasized that one needs to be very careful to make sure that this does not break other parts of the code. All this may be obvious (given that the “children” are not even accessible), but it may be worth mentioning…

We can certainly brainstorm about options for of improving the API here.

Does it honestly matter what our use case is?

Yes. Without knowing the use case, it’s impossible to provide a good (or even just sensible) solution.

Looking at the context here and in the other thread, it looks like the main “feature” that people are looking for is the access to the children of an entity. Of course, one could just make this “public” and call it a day. But… that entails some questions:

  • Imagine an entity (with children) is added to an EntityCollection (like the entities of a viewer). Should all children be added to the entity collection automatically?

  • Imagine one of the children from that entity is removed. Should that child be removed from all entity collections that contained it? Or should that child be removed from all entity collections that contain the parent?

  • Imagine one child is removed from an entity collection. Based on the descriptions here, the expectation would be that this child is also automatically removed from its parent. But this is not going to happen.

    The documentation of EntityCollection#remove currently says

    Removes an entity from the collection.

    Imagine this was now changed to say

    Removes an entity from the collection. If the removed entity is the child of a parent entity, then it will be removed from the ‘children’ of that parent, and its parent will be set to undefined

    That would be a (very subtle but) severe breaking change, meaning that it would literally break many existing applications and cause hard-to-debug errors. And it certainly would not be the desired behavior for all use-cases. Why should “removing an element from a collection” have side-effects that completely alter the structure of that object that is removed, and the structure of other objects that refer to this object?

  • How should the changes in the hierarchy be reflected in other entity collections?
    As an example code snippet:

    const collectionA = new Cesium.EntityCollection();
const collectionB = new Cesium.EntityCollection();

function createEntity(id, parent) {
  return new Cesium.Entity({
    position: Cesium.Cartesian3.fromDegrees(28.94, 41.07),
    id: id,
    parent: parent,
    billboard: {
      image: "../images/Cesium_Logo_overlay.png"
    } 
  });
}

const parent = createEntity("parentId", undefined);
const child = createEntity("childId", parent);

// Initially, the child has a parent
console.log(child.parent);

collectionA.add(parent);
collectionA.add(child);

collectionB.add(parent);
collectionB.add(child);

// Remove the child from one collection:
collectionA.remove(child);

// Here, child.parent should be undefined, right?
console.log(child.parent);

// And the `parent.children` should be empty, right?
console.log(parent._children);

// Should the child still be contained in collectionB?
console.log(collectionB.values.includes(child));

And at least in theory, all this refers to hierarchies, meaning that one has to ensure consistency across multiple collections and multiple levels of these hierarchies.

If I had to model some sort of “entity hierarchy” right now, I’d start with drafting a custom, domain-specific EntityHierarchyNode class, thoroughly think about what behavior I’d expect from that class, and refine that based on the exact use case that this is supposed to address.