Understanding interior and exterior surface / shells

[SeppBerkner]

I am currently writing my own cityjson2geojson converter to extract single surface types such as roof surfaces as a 2D geometry from CityJSON and convert this to GeoJSON. I have some issues to understand the exterior vs. interior ring problem. Let me explain in a bit more details:

The official CityJSON specification states the following:

• A "MultiSurface", or a "CompositeSurface", has an array containing surfaces, each surface is modelled by an array of arrays, the first array being the exterior boundary of the surface, and the others the interior boundaries.

• "Solid" has an array of shells, the first shell being the exterior shell of the solid, and the others the interior shells. Each shell has an array of surfaces, modelled in the exact same way as a MultiSurface/CompositeSurface.

Now I am trying to wrap my head around the two (it seems distinct) mentions of "interior shell" and "interior boundary". Perhaps my issue is that I think always 2D when I hear "interior [something]", but what is the difference between the two? For instance, the documentation page gives an example like the following for interior boundaries within one of the two exterior surfaces, which seems to align with the GeoJSON standard of interior rings:

{
  "type": "MultiSurface",
  "lod": "2.1",
  "boundaries": [
    [ [1, 2, 3, 4, 5], [6, 8, 7], [9, 12, 11, 10] ], [[14, 15, 16]]
  ]
}

However, the specification gives also an example for exterior / interior shells of a Solid type like this:

{
  "type": "Solid",
  "lod": "2",
  "boundaries": [
    //-- exterior shell
    [ [[0, 3, 2, 1, 22]], [[4, 5, 6, 7]], [[0, 1, 5, 4]], [[1, 2, 6, 5]] ], 
    //-- interior shell
    [ [[240, 243, 124]], [[244, 246, 724]], [[34, 414, 45]], [[111, 246, 5]] ] 
  ]
}

Here I am getting lost, as I don't understand what this interior shell actually represents geometrically. Sadly for this case there is also no drawing in the documentation pages. Why can I not add interior boundaries in the exterior shell and make the interior shell obsolete? And in the above example, is it true that each surface entry in the interior shell represents a "hole" in the exterior shell's surface with the same index? So every exterior shell has a hole in the example above?

[hugoledoux]

this should help: https://val3dity.readthedocs.io/2.5.1/definitions.html#iso19107-primitives

[SeppBerkner]

Thanks @hugoledoux ! This helped indeed. Can I assume that for my use case, where I only want to get the GroundSurface as well as the RoofSurface from the CityJSON as a 2D representation, I can ignore interior shells, as they are only relevant in the third dimension and holes in my surfaces of interest will be represented in the MultiSurface?

[hugoledoux]

yes exactly, only Solids have them.