Using the API

Need help, or want to share a macro? Post here!
User avatar
clel
Posts: 39
Joined: Mon Jun 13, 2016 10:30 am

Using the API

Postby clel » Tue Nov 26, 2019 1:12 pm

I am having problems finding functions used in scripts that I find here in the API on https://freecadweb.org/api/.

Example:

Code: Select all

shape = Part.Shape()
shape.read(importPath)
mesh = Mesh.Mesh()
mesh.addFacets(shape.tessellate(0.01))
mesh.write(exportPath)
I did not find Part.Shape() in the API, neither did I find a read() function in Shape(), I also did not find Mesh.Mesh() and its corresponding functions.

I even had problems with this code from a recorded macro:

Code: Select all

mesh = MeshPart.meshFromShape(Shape=shape,Fineness=0,SecondOrder=0,Optimize=1,AllowQuad=0)
Links to their occurence in the API are highly appreciated. I'd like to have some documentation for those functions.
User avatar
DeepSOIC
Posts: 7467
Joined: Fri Aug 29, 2014 12:45 am
Location: Saint-Petersburg, Russia

Re: Using the API

Postby DeepSOIC » Tue Nov 26, 2019 3:16 pm

Hi!
I'm not sure if these are in the api. It seems pretty useless to me.

You should browse it in py console. First, "import Part". Then, type "Part.Sh" and you'll see a list of suggestions. As you scroll through the list, docstrings will pop up as tooltips.
User avatar
clel
Posts: 39
Joined: Mon Jun 13, 2016 10:30 am

Re: Using the API

Postby clel » Tue Nov 26, 2019 3:59 pm

Ok, so the API available is rather incomplete then? Sad to hear that, it should maybe be mentioned on the API page.

So the only rather complete documentation is using the py console? This makes programming very hard. Thanks for the hint, though! It is probably very useful.
wmayer
Site Admin
Posts: 15471
Joined: Thu Feb 19, 2009 10:32 am

Re: Using the API

Postby wmayer » Tue Nov 26, 2019 4:04 pm

All of the mentioned functions are still available but you may have to first import the corresponding Python modules

Code: Select all

import Part
import Mesh
import MeshPart
User avatar
Kunda1
Posts: 7005
Joined: Thu Jan 05, 2017 9:03 pm

Re: Using the API

Postby Kunda1 » Tue Nov 26, 2019 4:32 pm

Browsing API from the Python console https://forum.freecadweb.org/viewtopic. ... 33#p272495
Please demonstrate using a remote text editor to substitute the Python editor in FreeCAD https://forum.freecadweb.org/viewtopic. ... 00#p346645
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
openBrain
Posts: 3349
Joined: Fri Nov 09, 2018 5:38 pm

Re: Using the API

Postby openBrain » Tue Nov 26, 2019 5:53 pm

As a side note to Kunda1's above post : https://forum.freecadweb.org/viewtopic. ... 70#p333170 ;)
vocx
Posts: 3245
Joined: Thu Oct 18, 2018 9:18 pm

Re: Using the API

Postby vocx » Wed Nov 27, 2019 9:28 am

clel wrote:
Tue Nov 26, 2019 3:59 pm
Ok, so the API available is rather incomplete then? Sad to hear that, it should maybe be mentioned on the API page.

So the only rather complete documentation is using the py console? This makes programming very hard. Thanks for the hint, though! It is probably very useful.
This page is incomplete, https://freecadweb.org/api/.

Why? Because the entire Doxygen generated documentation is around 5 GB in size, and the developers didn't want to upload and host all that.

The best way to get the programming documentation is to get the source code and compile it yourself. See Source documentation and Doxygen.

Nevertheless, there is also the issue that many Python functions in FreeCAD are defined from the C++ sources but don't have a corresponding .py file. That is, something like Part.Shape is not defined in a Python file, but in a C++ class, and this is exposed in Python as Part.Shape. In order to fully understand how to use some functions you need to understand the C++ code, refer to the C++ sources and documentation, and in some cases to the OpenCASCADE Technology (OCCT) documentation.
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.
User avatar
DeepSOIC
Posts: 7467
Joined: Fri Aug 29, 2014 12:45 am
Location: Saint-Petersburg, Russia

Re: Using the API

Postby DeepSOIC » Wed Nov 27, 2019 9:37 am

vocx wrote:
Wed Nov 27, 2019 9:28 am
Nevertheless, there is also the issue that many Python functions in FreeCAD are defined from the C++ sources but don't have a corresponding .py file. That is, something like Part.Shape is not defined in a Python file, but in a C++ class, and this is exposed in Python as Part.Shape.
Makes me wonder. It's not difficult to write a py script to auto browse all Part.something, gather all attributes, and generate a fake python module with all the classes having these methods with just docstrings. Then feed it to doxygen...
User avatar
looo
Posts: 3169
Joined: Mon Nov 11, 2013 5:29 pm

Re: Using the API

Postby looo » Wed Nov 27, 2019 10:06 am

DeepSOIC wrote:
Wed Nov 27, 2019 9:37 am
Makes me wonder. It's not difficult to write a py script to auto browse all Part.something, gather all attributes, and generate a fake python module with all the classes having these methods with just docstrings. Then feed it to doxygen...
Thinking about fake-python modules / abstraction layers, why not combine ideas and use the freecad namespace to put this all into?
But if we ever do anything in this direction, I guess we first need to define policies for the API which includes (Gui vs App handling, naming conventions, import-conventions, ...)
please help with my conda-packaging efforts: https://liberapay.com/looooo/
minimalistic blog: https://looooo.github.io/mini-blog/
vocx
Posts: 3245
Joined: Thu Oct 18, 2018 9:18 pm

Re: Using the API

Postby vocx » Wed Nov 27, 2019 4:42 pm

DeepSOIC wrote:
Wed Nov 27, 2019 9:37 am
Makes me wonder. It's not difficult ...
Are you asking, or are you saying this as a matter of fact? I think it is hard, and that's exactly why it hasn't been done before.

Yorik has mentioned it a few times, that in the past they thought about creating fake Python files with the information, and then documenting this with Sphinx, but it wasn't as straight forward. His attempts are in src/Doc/sphinx.

I would think it's hard to do this, but that's just my impression, I don't understand exactly how the whole wrapping of C++ classes works in FreeCAD. It would be great if there was a complete explanation by Werner or you or somebody who really knows.
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.