Talk:OSE Collaboration Protocol

Andrewusu's thoughts on FreeCAD git integration

FreeCAD v0.17 and newer

As of FreeCAD version 0.17 the WebTools Workbench allows Git integration through manual steps.

However *.fcstd files are binary files, specifically zip archives, and binary files aren't really suitable for version control tools like Git.

To prevent the explosion in space usage this mal-use would cause, a git filter should be set up for these *.fcstd files, such as:

1. hoijui/ReZipDoc Open Source Ecology Germany, requires JRE 8 or newer writeup
2. callegar/Rezip, written in bash, won't work on Windows (unless cygwin is used). Might have unwanted permissions changes on files due to the rezip?
3. Zippey, written in python, appears to be less optimal than the other two approaches, criticism of Zippey is in one of their write-ups. Zippey uses a different strategy than the other two so isn't compatible with them.

The rezip tools essentially re-zip the zip archive with a compression of 0, to allow git to compress better given changes through time.

If you have Java then hoijui/ReZipDoc would be more robust. callegar/Rezip in bash seems fine if you don't have Java installed and the git-config filter name matches what is in gitattributes. I expect any user can use either they want, as long as they have the global git config filter set up for the tool they have, and that filter name matches what is in the repo's .gitattributes

To see the results of the better compression, run `git gc`.

However, FreeCAD in a future version will support better integration with version control without such re-zip workarounds and additional workflow steps (e.g. FreeCAD automatically controlling git after a save instead of the user controlling git after saving the file).

FreeCAD v0.18 and newer (or v0.19 and newer?)

Brief view of Assembly3 assembly, document, and link organization. Sub-assemblies which are linked to an external document, will result in that external document being loaded and displayed as shown. While frozen they won't consume much memory.

Has realthunder's Assembly3 workbench. Supports links, which help eliminate prior memory limitations with larger assemblies, and need for such workarounds like File_Simplification. So long as the linked document is opened and the link is frozen, the assembly is displayed within the parent document as a single unmodifiable geometry. When the linked document is closed it won't be displayed anymore in the parent document.

I think it would be best if when the Assembly3 workbench isn't active,

That a simplified view of the model is presented in the Combo view, without the Constraints, Elements, Parts and additional hierarchy that Assembly3 at present introduces to FreeCAD:

The clutter of external documents in the tree view can be hidden by the setting 'View -> TreeView actions -> Single document'. But I'm still looking for a way to hide the Constraints, Elements, Parts containers- which would entail changing the TreeView to use a proper model-view separation. This change would also allow the ability to reorder items easily in the TreeView, something others would like to see implemented anyway.

FreeCAD v0.20 and newer

realthunder has made changes in FreeCAD to better support Version Control, however he writes "It is still in my fork. I think this feature will most likely land in the next 0.20 release".

Save as directory for version control integration in FreeCAD v0.20 and newer and realthunder's fork

realthunder has put in the plumbing to allow an FreeCAD module to automatically manage the version control of the CAD files.

My envisioned solution

While the solution with the FreeCAD WebTools Workbench and rezip should work... better possibilities exist, which will:

1. Better handle multiple documents, allowing re-use of work done (why invent the wheel twice!)
   1. Each linked sub-assembly of a parent assembly will have their own document, in their own git branch, with their own history, allowing other assemblies to make use of and update that subassembly without changing the original parent assembly.
2. Transparent git integration
   1. End-user does not have to interact with git or do any additional steps, other than save and enter a commit message
3. Module will notify user of any update to a document they're working on

Use FreeCAD v0.20 once available, or realthunder's present fork.

Set up a Module to respond to the signals. The signal data will include what files were modified/deleted/added. The module will:

1. Interact with git. e.g. Commit the changes to a new revision.
2. Push the new commit to a remote repository, if a remote repository is designated in the document properties.
3. Put sub-assemblies into their own branch, and use git sub-repo to include those sub-assemblies in a subdirectory in the main branch (likely master).
4. If a remote repository was designated for any sub-assembly, the module will push any change for that sub-assembly to that sub-assembly.

In addition to the module:

1. Add a means of adding properties to the document, so that the FreeCAD user can use the GUI to designate a remote version control repository to push/pull the changes to.
2. Add a means for the user to enter a commit message when they save the document.

Annotated Visual History

I'm not sure what would be the most optimal way to implement Annotated_Visual_History.

A simple idea would be to have:

1. An ".annotated_visual_history_cache" folder, which is listed in .gitignore (not versioned)
2. FreeCAD on opening a version controlled directory without, to interact with the module as the module iterates through git revisions, to cache each revision.
3. On each revision, take a set of isometric snapshots rotating around the assembly, resized to say 64x64 px.
   1. The module can possibly iterate through each revision without opening up the FreeCAD GUI.
4. An image processing utility will assign a complexity score to each snapshot, and the snapshot with the maximal complexity score will be selected as the thumbnail. A complexity score being a proxy measure of what image best illustrates the part!
   1. Filesize might suffice as an indirect measurement of complexity, the largest image being the most complex, otherwise,
   2. ImageMagick's identify might suffice, with a grep of a -verbose output, or a -features measurement, or
   3. FreeCAD 'Preferences->Document->SaveThumbnail' boolean indicates that a suitable feature may be in the FreeCAD API somewhere.
5. Have a FreeCAD workbench, such as the WebTools workbench, able to interpret the git log and these thumbnails in a meaningful way for the user

Or simpler would be to not make a cache, but just use FreeCAD's thumbnail generation as part of each versioned document. But this is binary and shouldn't be versioned if at all possible... caching is the optimal solution as illustrated earlier.

Related docs: Collaboration_Architecture, FreeCAD_101 This discussion page seemed like an ok sandbox to put my thoughts in before moving to a move formal page somewhere when I have a concrete solution.

--Andrewusu (talk) 23:22, 2 January 2021 (UTC) ]]