https://github.com/opensourcebim/bimbots-freecad
A FreeCAD plugin to communicate with BIMbots services
https://github.com/opensourcebim/bimbots-freecad
Last synced: 10 months ago
JSON representation
A FreeCAD plugin to communicate with BIMbots services
- Host: GitHub
- URL: https://github.com/opensourcebim/bimbots-freecad
- Owner: opensourceBIM
- License: lgpl-2.1
- Created: 2019-02-11T16:45:49.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2024-06-06T13:39:38.000Z (over 1 year ago)
- Last Synced: 2025-03-24T17:14:43.346Z (11 months ago)
- Language: Python
- Homepage:
- Size: 4.99 MB
- Stars: 13
- Watchers: 6
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# BIMbots-FreeCAD
A FreeCAD plugin to communicate with BIMbots services - http://bimbots.org/
**Warning - the BIMbots service has been retired and this addon is now obsolete**
This FreeCAD plugin allows a user to:
1. Upload a FreeCAD model or selected parts of a FreeCAD model to a BIMBots instance (usually a [BIMServer](http://bimserver.org/) with external services enabled)
2. Perform different services and analyses on their model
3. Read said results in FreeCAD (usually in the form of a text report) or a BCF file (not yet supported - see below)
This plugin is written in Python and consists of a single all-in-one Python file along with a companion FreeCAD macro for convenience.
It can be used in several ways:
### Run BIMBots within FreeCAD
* The main usage is to work within [FreeCAD](https://www.freecadweb.org) and be simply launched as a macro.
* If you have the [BIM Workbench](https://github.com/yorikvanhavre/BIM_Workbench) installed, this BIMBots plugin will be automatically detected at start and you will find a **BIMBots** command under **Utils** menu.
### Run BIMBots from the CLI
The BIMBots plugin can also be run directly from the command line terminal, in which case it prints a list of services it was able to reach, or imported as a python module (Python 2 and Python 3 compatible), in which case you have access to several utility functions to retrieve and communicate with BIMbots services. So essentiall this can also be used as a library to build your own BIMBots client.
Check the [API documentation](doc/documentation.md) page (autogenerated with [pdoc](https://pdoc3.github.io/pdoc/)) and the [FreeCAD GUI documentation](doc/ui-documentation.md).
### How to install
In FreeCAD, just head to menu **Tools -> Addons Manager**, locate the BIMBots addon, press the **Install** button, and restart FreeCAD.
### How to use
Once installed, you will find a **BIMBots** entry under menu **Macro -> Macros**. If you have the [BIM Workbench](https://github.com/yorikvanhavre/BIM_Workbench) also installed, the BIMBots plugin will be automatically detected at start and you will find a **BIMBots** command under menu **Utils**.
Refer to the [documentation](doc/ui-documentation.md) for complete use instructions.
### Features
#### When used as a Python module, it can:
* Retrive a list of BIMbots services
* Authenticate with any of the services
* Keep authentication credentials in a config file
* Test services (send a minimal test IFC file that is guaranteed to work)
* Send actual IFC files
* Get the results
#### When running inside FreeCAD:
* All functionality is available from the GUI
* Auto-discover available services
* Add/remove custom servers
* Authenticate with services
* Send model data to any service
* Display JSON or text reports
* Double-click results (JSON results only) to select corresponding objects in the 3D view
#### To do (help welcome!):
* Handle Context-Id (reuse an already sent model slot)
* Handle asynchronous connection (don't wait and freeze the FreeCAD interface while data is being transmitted)
* Implement display of BCF files in FreeCAD (in progess - Part of a [GSOC](https://forum.freecadweb.org/viewtopic.php?f=8&t=35465) project)
#### Quick how-to use from Python
```
>>> import bimbots
>>> bimbots.get_service_providers()
```
This returns a dictionary containing the different service providers found (both auto-discovered and manually added via the FreeCAD UI):
```
[{u'listUrl': u'https://ifcanalysis.bimserver.services/servicelist', u'name': u'ifcanalyses'},
{u'listUrl': u'http://localhost:8080/servicelist', u'name': u'Default localdev BIMserver',
u'description': u'Default localdev BIMserver'}, {u'listUrl': u'http://localhost:8081/servicelist',
u'name': u'2nd localdev BIMserver', u'description': u'2nd localdev BIMserver'},
{u'listUrl': u'http://localhost:8082/servicelist', u'name': u'Default JAR runner',
u'description': u'Default JAR runner'}, {u'listUrl': u'https://thisisanexperimentalserver.com/servicelist',
u'name': u'Experimentalserver.com', u'description': u'Experimental BIMserver'}]
```
Then, using one of the "listUrl" above:
`>>> bimbots.get_services('http://localhost:8082/servicelist')`
This returns a list of services offered by the given server (adding the /servicelist is optional):
```
[{u'inputs': [u'IFC_STEP_2X3TC1'], u'resourceUrl': u'http://localhost:8082/services',
u'description': u'IFC Analytics Service', u'outputs': [u'IFC_ANALYTICS_JSON_1_0'],
u'providerIcon': u'/img/bimserver.png', u'provider': u"Yorik's test BIMserver",
u'oauth': {u'tokenUrl': u'http://localhost:8082/oauth/access',
u'registerUrl': u'http://localhost:8082/oauth/register',
u'authorizationUrl': u'http://localhost:8082/oauth/authorize'},
u'id': 2097206, u'name': u'IFC Analytics Service'},
{u'inputs': [u'IFC_STEP_2X3TC1'], u'resourceUrl': u'http://localhost:8082/services',
u'description': u'BIMserver plugin that provides an analysis of a model and and outputs it into json',
u'outputs': [u'UNSTRUCTURED_UTF8_TEXT_1_0'], u'providerIcon': u'/img/bimserver.png',
u'provider': u"Yorik's test BIMserver",
u'oauth': {u'tokenUrl': u'http://localhost:8082/oauth/access',
u'registerUrl': u'http://localhost:8082/oauth/register',
u'authorizationUrl': u'http://localhost:8082/oauth/authorize'},
u'id': 2162742, u'name': u'Simple Analyses Service'}]
```
The next step, if you want to use a service, is to authenticate with it. This is done in two steps. Step 1 is done using one of the "registeUrl" above:
`>>> bimbots.authenticate_step_1('http://localhost:8082/oauth/register')`
This will return a dict with keys that identify our BIMbots plugin on the given server.
`>>> bimbots.authenticate_step_2('http://localhost:8082/oauth/authorize', 'freecad', 'Simple Analyses Service')`
Client_id and service_name will be returned by the step 1 above. This will pop up a browser window, which will access the given BIMbots server, on which you must have a valid user already logged in. You will land on a page that asks you to confirm. Upon confirmation, you will receive a token and an url. Save them to your config file with:
`>>> bimbots.save_authentication('http://localhost:8082/', 2097206, 'Simple Analyses Service', service_url, token)`
The first URL is used to bind this service to a given server in the config file. You can use either the server name, as I did above, or the /servicelist URL obtained by the first step above in these instructions. service_id, service_name are obtained in step 1 above, and service_url, token are obtained via the web interface opened in step 2.
After you properly registered the service, you can now try sending it a test file:
`send_test_payload('http://localhost:8082/', 2097206)`
There are more functions to interact with services. Check the [API documentation](doc/documentation.md) for the full list of available functions.