FreeCAD Nodes (renamed from fc_nodes)

Show off your FreeCAD projects here!
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
User avatar
j8sr0230
Posts: 140
Joined: Thu Apr 07, 2022 8:59 am
Location: Chemnitz
Contact:

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by j8sr0230 »

drmacro wrote: Wed Dec 14, 2022 1:32 am Has there been any documentation created or added to the gihub?
I am currently researching possible documentation frameworks that will allow me to maintain high quality documentation with reasonable effort (although the nodes will probably still change here and there). I ask for some patience, but shouldn't take too much longer ;)
Codelink on GitHub: https://github.com/j8sr0230/codelink
Codelink on PiPy: https://pypi.org/project/codelink/
FreeCAD Nodes Workbench on GitHub: https://github.com/j8sr0230/Nodes
User avatar
j8sr0230
Posts: 140
Joined: Thu Apr 07, 2022 8:59 am
Location: Chemnitz
Contact:

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by j8sr0230 »

Hello friends,
the latest update includes the trigonometric functions sine, cosine and tangent as well as the vector cross product! The application example shows a sine curve mapped to an arbitrary 3D-BSpline. Have fun with it!
Sinus mapped to bspline
Sinus mapped to bspline
nodes_sin_on_crv.gif (425.09 KiB) Viewed 2941 times
Codelink on GitHub: https://github.com/j8sr0230/codelink
Codelink on PiPy: https://pypi.org/project/codelink/
FreeCAD Nodes Workbench on GitHub: https://github.com/j8sr0230/Nodes
drmacro
Veteran
Posts: 8867
Joined: Sun Mar 02, 2014 4:35 pm

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by drmacro »

j8sr0230 wrote: Wed Dec 14, 2022 11:54 am
drmacro wrote: Wed Dec 14, 2022 1:32 am Has there been any documentation created or added to the gihub?
I am currently researching possible documentation frameworks that will allow me to maintain high quality documentation with reasonable effort (although the nodes will probably still change here and there). I ask for some patience, but shouldn't take too much longer ;)
You don't intend to use/add to the FreeCAD wiki as most (all?) workbenches do?
Star Trek II: The Wrath of Khan: Spock: "...His pattern indicates two-dimensional thinking."
User avatar
j8sr0230
Posts: 140
Joined: Thu Apr 07, 2022 8:59 am
Location: Chemnitz
Contact:

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by j8sr0230 »

drmacro wrote: Wed Dec 14, 2022 12:02 pm You don't intend to use/add to the FreeCAD wiki as most (all?) workbenches do?
My intention is definitely to create a static FreeCAD wiki. However, I can well imagine linking from the wiki to a dynamic, automatically generated ReadTheDocs documentation to keep the documentation effort manageable. What is your opinion on this solution?
Codelink on GitHub: https://github.com/j8sr0230/codelink
Codelink on PiPy: https://pypi.org/project/codelink/
FreeCAD Nodes Workbench on GitHub: https://github.com/j8sr0230/Nodes
drmacro
Veteran
Posts: 8867
Joined: Sun Mar 02, 2014 4:35 pm

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by drmacro »

j8sr0230 wrote: Wed Dec 14, 2022 12:12 pm
drmacro wrote: Wed Dec 14, 2022 12:02 pm You don't intend to use/add to the FreeCAD wiki as most (all?) workbenches do?
My intention is definitely to create a static FreeCAD wiki. However, I can well imagine linking from the wiki to a dynamic, automatically generated ReadTheDocs documentation to keep the documentation effort manageable. What is your opinion on this solution?
I don't have a solution to propose. I have done some work on the FC wiki.

Doesn't ReadTheDocs generate fro the code comments? I looked at some of the Nodes code and didn't see comments...

I, admit, I've not looked at ReadTheDocs.
Star Trek II: The Wrath of Khan: Spock: "...His pattern indicates two-dimensional thinking."
User avatar
j8sr0230
Posts: 140
Joined: Thu Apr 07, 2022 8:59 am
Location: Chemnitz
Contact:

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by j8sr0230 »

drmacro wrote: Wed Dec 14, 2022 12:26 pm [...] Doesn't ReadTheDocs generate fro the code comments? I looked at some of the Nodes code and didn't see comments...

I, admit, I've not looked at ReadTheDocs.
All nodes inherit from the FCNNodeModel class located in the ./core/nodes_default_node.py module. All classes in this module enable developers to program their own nodes, serve as API and are documented using DocString and comments. The same applies to the functions in the ./core/nodes_utils.py module. Only the documentation of the individual node implementations I have omitted until now, because they usually perform simple arithmetic operations or delegate to FreeCAD's OCC-API (Part). For this user documentation I envision a format based on Blender's Geometry Nodes documentation (see https://docs.blender.org/manual/en/late ... ength.html).
Codelink on GitHub: https://github.com/j8sr0230/codelink
Codelink on PiPy: https://pypi.org/project/codelink/
FreeCAD Nodes Workbench on GitHub: https://github.com/j8sr0230/Nodes
drmacro
Veteran
Posts: 8867
Joined: Sun Mar 02, 2014 4:35 pm

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by drmacro »

j8sr0230 wrote: Wed Dec 14, 2022 1:34 pm ...

All nodes inherit from the FCNNodeModel class located in the ./core/nodes_default_node.py module. All classes in this module enable developers to program their own nodes, serve as API and are documented using DocString and comments. The same applies to the functions in the ./core/nodes_utils.py module. Only the documentation of the individual node implementations I have omitted until now, because they usually perform simple arithmetic operations or delegate to FreeCAD's OCC-API (Part).
Is the target end user to be folks who know the OCC API? And thus can extrapolate what the nodes do from their existing experience?

I attempted to look at a node that you recently added a input to. When I looked at the code, other than the standard license block, the code was spartan.

I'm just used to seeing doc strings on all definitions statements that define the arguments, etc. I think this is usually expected (and is why help() on any Python objects will provide more detail.)
For this user documentation I envision a format based on Blender's Geometry Nodes documentation (see https://docs.blender.org/manual/en/late ... ength.html).
This link is a perfect example of developers documentation. It is nearly useless to an end user. What is "Standard geometry input."? If a end user is attempting learn, then this is not obvious. Great if they already know and just need a reference. If not then the search begins: "what is standard geometry?", is it a list? a dictionary? a tuple? Probably obvious to the programmer...not the user.

Thus there is user documentation and developer documentation, the later not being much help to the former.

Are there facilities in ReadTheDocs to differentiate?
Star Trek II: The Wrath of Khan: Spock: "...His pattern indicates two-dimensional thinking."
User avatar
flachyjoe
Veteran
Posts: 1869
Joined: Sat Mar 31, 2012 12:00 pm
Location: Limoges, France

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by flachyjoe »

Hi,
j8sr0230 wrote: Wed Dec 14, 2022 12:12 pm automatically generated ReadTheDocs documentation
please take translation easiness into account. FreeCAD wiki has a very good amount of translation and an active translators team who may not go on another platform.
drmacro wrote: Wed Dec 14, 2022 4:45 pm Probably obvious to the programmer...not the user.
Node user IS a programmer because graphed or wrote programs are not so distinct. Even if Nodes tends to a higher level than python① it needs programming logic.
①for a python level graphical scripting language, see my FCPD attempt.
- Flachy Joe -
Image
drmacro
Veteran
Posts: 8867
Joined: Sun Mar 02, 2014 4:35 pm

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by drmacro »

flachyjoe wrote: Wed Dec 14, 2022 7:27 pm ...
drmacro wrote: Wed Dec 14, 2022 4:45 pm Probably obvious to the programmer...not the user.
Node user IS a programmer because graphed or wrote programs are not so distinct. Even if Nodes tends to a higher level than python① it needs programming logic.
①for a python level graphical scripting language, see my FCPD attempt.
I'm proficient in Python and several other programming languages. I'm also familiar with Sverchok and animation nodes in Blender.

When learned animation nodes in Blender, I didn't need to learn the Blender API...because there was documentation meant to allow someone to use the tool...not learn to program.

Am I misunderstanding your comment?
Star Trek II: The Wrath of Khan: Spock: "...His pattern indicates two-dimensional thinking."
User avatar
j8sr0230
Posts: 140
Joined: Thu Apr 07, 2022 8:59 am
Location: Chemnitz
Contact:

Re: FreeCAD Nodes (renamed from fc_nodes)

Post by j8sr0230 »

I don't think any of us doubts that FreeCAD Nodes needs solid documentation, that grows up along with the project itself.
flachyjoe wrote: Wed Dec 14, 2022 7:27 pm [...] please take translation easiness into account. FreeCAD wiki has a very good amount of translation and an active translators team who may not go on another platform. [...]
This is a very good point that convinces me to puplish the user documentation via the FreeCAD Wiki. Thanks for this!
drmacro wrote: Wed Dec 14, 2022 4:45 pm [...] This link is a perfect example of developers documentation. It is nearly useless to an end user. What is "Standard geometry input."? If a end user is attempting learn, then this is not obvious. Great if they already know and just need a reference. If not then the search begins: "what is standard geometry?", is it a list? a dictionary? a tuple? Probably obvious to the programmer...not the user. [...]
Perhaps Blender's Geometry Nodes documentation was not a suitable example (although I actually find it quite successful). With that, I just wanted to suggest a basic format for the FreeCAD Nodes Wiki. I think the developers of Sverchok have done a very good job and it makes sense to stick to such a template (see https://nortikin.github.io/sverchok/doc ... t_arc.html). What do you think? This does not exclude to provide also the individual nodes with the corresponding DocStrings ...
Codelink on GitHub: https://github.com/j8sr0230/codelink
Codelink on PiPy: https://pypi.org/project/codelink/
FreeCAD Nodes Workbench on GitHub: https://github.com/j8sr0230/Nodes
Post Reply