Project: Build132d Shape History

[njourdane]

I'm working a tool used to manage and visualize the modification history of Build123D objects. Useful for debugging, doesn't require an IDE debugger.

It's in early stage of development, but I have a proof of concept.

Source code

Installation

This package is published on Pypi:

pip install bd_shape_history

Usage

Assuming a simple part created in 3 steps:

box = _.Box(3, 3, 1)
cbox = _.chamfer(box.edges()[0], 0.5)
cboxh = cbox - _.Cylinder(0.75, 1)

We can build the history with:

hm = ShapeHistory.from_globals()

Note: from_globals can take several attributes used to filter the parts to put in the history.

Then we can display the diff (here with VScode OCP CAD viewer):

ov.set_defaults(render_edges=False)
ov.show(*hm.diff(), names=hm.labels())

This shows a visual diff between each step:

Notice how the object is colored on each step:

• new faces and edges are green and light green;
• unchanged faces and edges are gray and black;
• modified faces and edges are dark green and olive

How does it work

ShapeHistory compares the hash of faces, edges and vertices between each steps:

• a face or edge whose hash is found on the previous step is considered unmodified;
• a face whose all edges are not found in the previous step is considered added (and same for edge / vertices);
• otherwise the face or edge is considered modified;

Planned features

• support 2d part history;
• more configuration (color settings, etc.)
• negative diff: display which face has been deleted instead which has been added, or a mix of both;
• modification map: color each face and edge according to its modification time, based on a color map.
• modification graph: print a graph displaying an overview of all modifications on all steps.
• improve low-level api:
  • blame: for a given face or edge, return the step that created / modified / deleted it;
  • low-level diff: return the faces and edges altered on a given step, or between 2 given steps;
  • aliases: allow to define a custom label on a face or edge;

Feedback

What do you think about this project?
Do you think you might use it? Why?
Do you expect some features to be included in the roadmap?

[jdegenstein]

Very interesting and valuable work here! This is something I have wanted for a long time so I really see the value in it! Now that OCPCV can render to a file I wonder if it would be possible to couple bd_shape_history into a github action that will add a bot comment on a pull request showing the visual diff result?

FYI there are changes coming with OCCT/OCP 7.8+ to the built-in hashing functionality (mostly for the good as it reduces collision probability significantly, but the API is changing a bit).

[njourdane]

Very interesting and valuable work here! This is something I have wanted for a long time so I really see the value in it!

Thank you so much for this encouraging feedback!

Now that OCPCV can render to a file I wonder if it would be possible to couple bd_shape_history into a github action that will add a bot comment on a pull request showing the visual diff result?

Very interesting suggestion. This assumes to allow to compare two files (instead comparing two steps on a single file), and eventually an integration with git. Since the hash of a same shape changes on each run, it's a bit challenging. More importantly, I don't even know how a user could do this (maybe using a cli script?). Any ux suggestions are welcome here.

FYI there are changes coming with OCCT/OCP 7.8+ to the built-in hashing functionality (mostly for the good as it reduces collision probability significantly, but the API is changing a bit).

Thank you for the information, I will check if OCP 7.8 breaks something.

[njourdane]

I updated my project so you can see the diff between parts located in different files, using a new hash function based on ocp_tesselate (see the example).

There is no cli script yet, though.

I made a cli script, you can use it like this:

ocp_diff this_file:var_name that_file:var_name diff.png

For instance: ocp_diff ./examples/a.py:box ./examples/b.py:box img.png

[gumyr]

Cool project. I took a very brief look at your code - it seems like you are using the label attribute to keep track of stuff. As end users often assign a label to their parts it seems like there would be a conflict there. If so, maybe build123d could introduce a new attribute that this project could use? I've been thinking about a user_defined attribute (or something like that) that isn't used by build123d itself but would be available for uses like this. If it was a dict of: project_name : Any then it could even avoid conflicts between multiple projects.

[njourdane]

Cool project.

Thanks!

I took a very brief look at your code - it seems like you are using the label attribute to keep track of stuff.

Labels are not used to compares shapes but for practicality, in order to manually compare the labels on each step in the ocp-vscde viewer:

In fact I don't really use them, but I though it was useful since shape labels are preserved on each step as long as the shape is untouched.

But yes indeed, it could be better to put labels explicitly, like hm.name_shapes().