Better to have usage scenarios...

[xiongyw]

It would be great to add a section in the begining of the typical usage scenarios of the API (with a short yet concrete example), for new users of FreeCAD.

I came to this repository from this thread. The answer from edwilliams16 makes a lot of sense to me, as I can test it right away in the Python console and see the effect... but I cannot yet make connection from that to the concept of ScriptedObject and your documentation.

FreeCAD wiki on ScriptedOjbects confuses me. For example:

The Python code that you write to create parametric objects is never saved inside a file. This means that if you open a file containing such an object on another machine, if that python code is not available on that machine, the object won't be fully recreated.

The python script already created the objects which are stored in the .FCStd file, why a receiver of the file still need the script to recover the objects? Probably my usage scenario is too simple: using a script to create the bodies, instead of using mouse and keyboard (probably just for the 1st time). If I want to change the object somehow later on (usually not the final feature...but changing a middle feature most likely will trigger TNP which leads to a great amount of effort to fix the following features), I just change the script, and re-run the script to create a new .FCStd file to replace the old one.

Thanks.

[mnesarco]

It would be great to add a section in the begining of the typical usage scenarios of the API (with a short yet concrete example), for new users of FreeCAD.

This is certainly not for new users of FreeCAD but for extensions developers. There is a complete section of typical usage scenarios in the document:

https://github.com/mnesarco/fcapi/blob/main/docs/documentation.md#code-examples

I came to this repository from this thread. The answer from edwilliams16 makes a lot of sense to me, as I can test it right away in the Python console and see the effect... but I cannot yet make connection from that to the concept of ScriptedObject and your documentation.

FreeCAD wiki on ScriptedOjbects confuses me. For example:

The Python code that you write to create parametric objects is never saved inside a file. This means that if you open a file containing such an object on another machine, if that python code is not available on that machine, the object won't be fully recreated.

That text is from the wiki, not from my documentation. But I can explain it better:

If you want to create builtin objects like Cubes, Cones, Spheres, or any Feature provided by FreeCAD or by a Workbench, you do not need a ScriptedObject, you just have to call some minimal code in a macro or in the console. This is not considered a FreeCAD extension. So in this case you don't have to share your code and the .FCStd file can be opened freely in any machine.

On the other hand, if you want to create a new custom Feature with custom behavior or custom visualization, you need to create a ScriptedObject and in that case you need to provide the code to the machines where the object needs to be executed.

The python script already created the objects which are stored in the .FCStd file, why a receiver of the file still need the script to recover the objects? Probably my usage scenario is too simple: using a script to create the bodies, instead of using mouse and keyboard (probably just for the 1st time). If I want to change the object somehow later on (usually not the final feature...but changing a middle feature most likely will trigger TNP which leads to a great amount of effort to fix the following features), I just change the script, and re-run the script to create a new .FCStd file to replace the old one.

For this scenario you don't need ScriptedObject api. A simple macro is enough. And your python code does not need to be available in the other machine.

[xiongyw]

Thanks, @mnesarco. Your answer is informative and resolved my doubts.