Skip to content

A small python library of pivy/coin3D-based objects for renderning lines / nodes at the scenegraph level for user interface feedback. Implemented originally as a part of the FreeCAD Trails Workbnech.

License

joelgraff/pivy_trackers

Repository files navigation

pivy_trackers

pivy_trackers is a 2D geometry library built on pivy, the python bindings library for Coin3D that is a part of the FreeCAD project.

A "tracker" is simply geometry which "tracks with" the user as they interact with a tool to provide dynamic visual feedback. A good example may be generating a "rubber band box" as a user clicks and drags over an area to select objects to provide a visual representation of the limits of their selection.

At the moment, pivy_trackers is tied to the FreeCAD API, though it may be adapted for another Coin3D application which implements pivy.

Examples

Check out the wiki for tracker examples

Motivation

Creating custom tools and workbenches in FreeCAD is greatly facilitated by the nearly one-to-one exposure of it's C++ API in Python, with the pivy Python bindings exposing to the underlying Coin3D scenegraph C++ API.

However, creating custom tools in FreeCAD that provide intuitive, visual feedback to the user poses a challenge as developers are forced to interact with the Coin3D scenegraph directly through pivy.

Pivy_trackers eases this process and provides several basic features which are valuable to most any 3D modelling tool, like selection / multi-selection, dragging, and rotation, insulating the developer from most of the inner workings of the scenegraph while still allowing for full customization of the tracker behaviors.

Requirements

While pivy_trackers aims to be dependent only on pivy (and, by extension, Coin3D), it is currently tied to FreeCAD's object libraries.

Specifically:

Additionally, pivy_trackers relies on the following projects included as git submodules:

IDE's which support git should update the submodules without issue. However, the user is encouraged to refer to the github submodule documentation for furtrher assistance, as extra steps may be required to update the submodule paths in the project.

Note: The PySide dependency for FreeCAD, specifically, is a unique package maintained via the FreeCAD-Daily PPA.

Getting Started

Clone the project into a path visible through your project's top-level module. Note the --recursive switch, which ensures the FreeCAD_python_support submodule is also cloned:

cd /my/project/top/module/path
git clone --recursive https://github.com/joelgraff/pivy_trackers.git

Usage

Pivy_trackers should be visible as a top-level module. Thus, pivy_tracker classes can be imported directly as:

from pivy_trackers.trait.base import Base

Reference

Note that while the pivy API is not directly documented, it is a one-to-one exposure of the Coin3D API. Thus, reviewing the Coin3D documentation will provide the user with most relevant implementation details.

Additional support can be found at the FreeCAD forums: https://forum.freecadweb.org/

Contributors

Take a look at the wiki and project KanBan board for more information. Feel free to reach out to me here or through the forums. Contributions are greatly appreciated!

License

GNU LGPL v2.1

About

A small python library of pivy/coin3D-based objects for renderning lines / nodes at the scenegraph level for user interface feedback. Implemented originally as a part of the FreeCAD Trails Workbnech.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages