pypolaris

Cross-platform SWIG/C++ wrapper for NDI Polaris trackers.

• CAPIcommon/: NDI communication library.
• CAPIsample/src/main.cpp: Python-facing implementation.
• pypolaris.i and pypolaris.h: SWIG interface and public wrapper API.
• sroms/: tool definition files used by examples and local testing.
• CMakeLists.txt: the only native build definition.

Build from the repository root:

uv run --python 3.12 python build-system/build_wheel.py pypolaris

This creates one wheel for the selected Python and the current operating system. Cross-platform wheels are built by the repository's GitHub Actions matrix, not by cross-compiling this command locally.

Multiple-object support introduced in version 0.0.9 remains available. Pass the tool definitions in a StringVector to Initialize; the corresponding measurements and visibility flags are exposed through objs and objIDs:

objects = pypolaris.StringVector()
objects.push_back(b"coil-1.rom")
objects.push_back(b"coil-2.rom")
tracker.Initialize(b"COM1", b"NBSprobe", b"NBSref", objects)
tracker.Run()
print(tracker.objs, tracker.objIDs)

The single-object Initialize overload and the obj/objID attributes from version 0.0.7 remain available for compatibility.

The native calls release Python's GIL while waiting for the tracker. Access to each Polaris connection is serialized, so concurrent Python work can continue without interleaving device commands. Separate pypolaris instances no longer share a connection or tracking state.

For the lowest per-frame overhead, use ReadFrame() instead of Run(). It returns numeric values directly and avoids creating the legacy CSV strings:

frame = tracker.ReadFrame()
if frame.status == 0:
    for transform in frame.transforms:
        if transform.visible:
            print(transform.toolHandle, transform.tx, transform.ty, transform.tz)

frame.status is 0 on success, -1 after a transport/parse failure and -2 when tracking has not been started. Run() remains backward compatible, updates probe, ref, objs and their ID flags, and returns 1, -1 or -2 for those same states.

Do not commit generated pypolaris.py, _pypolaris.*, CMake build trees or wheels. The shared builder stages those files automatically.