Solid vs Shell

[A-Walrus]

I'm a bit confused by the difference between these two types.
The dos for shell:

/// A 3-dimensional closed shell
///
/// # Implementation Note
///
/// The faces that make up a shell should be closed ("watertight"). This is not
/// currently validated.

The docs for solid:

/// A 3-dimensional shape
///
/// # Implementation Note
///
/// The shells that form the boundaries of the solid must not intersect. This is
/// not currently validated.

It says that the shells that form the boundaries of the solid must not intersect, which to me sounds like a disjoint union / group, which confuses me further because we also have the Group and Shape types.
Can you help me understand?
PS: Once I understand I'll try to update the docs to make it clearer for the next contributors.

[hannobraun]

Thank you for the question, @A-Walrus! This is definitely under-documented.

Solid is a solid body. Shell is a single closed set of faces ("closed" meaning there are no gaps in the shell, if it's valid). A solid body could have fully enclosed cavities inside of it. Think about a hollow sphere, for example, where the hollow room inside has no connection to the outside. Such a solid body has an outer shell, as well as an inner shell for each enclosed cavity.

(This would be different, if the cavities inside are connected to the outside. If you have a hollow sphere with a hole that connects to the inside, then it's a Solid with just a single Shell.)

As for the comparison to Group and Shape, these are very different things. First, let's note that Solid, Shell, and the other object types are located in fj-kernel. fj-kernel uses boundary representation to represent shapes. Solid, Shell, and all the other object types are the implementation of this boundary representation.

Shape is a trait located in fj-operations, and its implementations are located in fj. Shape and its implementations also represent shapes, but this is a rather abstract representation. For example Group imlements Shape, and group contains two other shapes, which could be sweeps, for example, which in turn each contain a 2D shape and a vector to sweep it along. Basically, this structure I've described here is saying "take sketch A and sweep it along path X, then take sketch B and sweep it along path Y, finally combine the two resulting bodies into a group of bodies".

This representation is simple and powerful, allowing you to represent all kinds of shapes rather easily, just by defining the right kinds of Shape implementations and combining them. But it's also rather useless. How am I going to render such a structure? How am I going to convert it into a triangle mesh, so I can export it to STL/3MF for 3D printing? Well, the answer is, I'm not. I need a different representation for that, for example the boundary representation that is implemented in the kernel.

So, basically, the big picture is this:

• We have the shape operations (group, sweep, etc.) defined in fj, to give the user an easy tool to describe shapes in model code.
• We implement Shape for all these operations in fj-operations, which creates a bridge to the boundary representation in fj-kernel, through Shape::compute_brep.
• Finally, we have fj-kernel, which implements the boundary representation. This is messy and complicated, but we can use it to actually do something with the shapes, not just describe them.

Taking it back to Solid and Group: Group no longer exists as a concept, once it's translated into boundary representation. It will end up as a Solid with multiple exterior Shells.

(As a side note, we could implement a second kernel, for example one based on function representation, and create a new Shape::compute_frep method to translate to it. I don't intend to do that, I'm just noting it to underline the fact that fj/fj-operations and fj-kernel are separate things, which is why fj-kernel knows nothing about Group.)

Once I understand I'll try to update the docs to make it clearer for the next contributors.

That would be great!

[A-Walrus]

Thanks for the thorough response! I'll update the docs accordingly 👍

[hannobraun]

Thank you, I'm looking forward to it!

Don't hesitate to ask more questions, if anything is unclear. I'm very interested in having better documentation.