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.
Check out the wiki for tracker examples
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.
While pivy_trackers aims to be dependent only on pivy (and, by extension, Coin3D), it is currently tied to FreeCAD's object libraries.
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.
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
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
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/
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!