Metadata-Version: 2.2
Name: sky-tracker-sdk
Version: 0.2.2
Summary: Sky Tracker — C++ tracking core with Python and Node.js SDK
Keywords: tracking,computer-vision,edge,raspberry-pi,drone
License: Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Provides-Extra: cv
Requires-Dist: opencv-python>=4.8; extra == "cv"
Description-Content-Type: text/markdown

# Sky Tracker SDK

C++ tracking core for fast-moving small objects — drone, aircraft, bird detection and tracking. No GPU required.

## Install

```bash
pip install sky-tracker-sdk
```

## License

A valid license key is required at runtime. Set it as an environment variable:

```bash
# Windows
set SKY_TRACKER_LICENSE_KEY=SKT1.<your-token>

# Linux / macOS
export SKY_TRACKER_LICENSE_KEY=SKT1.<your-token>
```

Or drop a `sky_tracker.lic` file next to your script — the SDK finds it automatically.

## Quick Start

```python
import cv2
import sky_tracker

cap = cv2.VideoCapture("video.mp4")
ok, frame = cap.read()

tracker = sky_tracker.Tracker("default")
tracker.lock(frame, (469, 409, 26, 38))  # x, y, w, h

while cap.isOpened():
    ok, frame = cap.read()
    if not ok:
        break
    result = tracker.update(frame)
    if not result.lost:
        cx, cy = result.center()
        print(f"frame target at ({cx:.1f}, {cy:.1f})  confidence={result.confidence:.2f}")
```

## Tracker Profiles

| Profile | Best for |
|---------|----------|
| `default` | Correlation identity and stable foreground boxes; grayscale scoring and bounded recovery |
| `correlation` | Correlation-led identity and stable selected-object tracking |
| `adaptive` | Correlation identity with scheduled foreground bbox fitting |
| `legacy` | Previous default settings from v0.1.12 for existing tuned applications |
| `correlation-quality` | Opt-in normalized correlation with appearance verification and a fixed selection size |
| `adaptive-quality` | Opt-in quality engine with its own adaptive foreground alignment |

For `default` and `adaptive`, automatic search uses the initial box's longest side:
64 pixels up to 16 px, 128 pixels through 80 px, and 256 pixels above 80 px.
`correlation` retains its v0.1.12 sizing: 128 pixels through 80 px and 256 above 80 px.
The quality profiles use their own 128/256 search policy and stricter evidence thresholds.
They are optional; existing profile names retain the same tracking behavior. See
[quality engine details](docs/correlation-quality-update.md).

The default profile includes foreground box fitting, so neither a profile nor a
search flag is needed. `adaptive` retains color contrast and appearance scoring. `--target-correlation-search` remains an optional override.
See [adaptive geometry stability and validation](docs/adaptive-geometry-jitter.md)
and [default profile performance](docs/default-tracker-performance.md).

Version 0.2.0 changes the default tracking behavior. To retain the previous default,
use CLI `--profile legacy`, Python `sky_tracker.Tracker("legacy")` (or set
`TrackerConfig.profile = "legacy"`), or Node `{ profile: "legacy" }` with the 0.2.2 runtime.
Existing Pi profile aliases still select the improved `default`.
See [0.2.2 release notes](docs/release-0.2.2.md) and the
[0.2.0 migration guide](docs/release-0.2.0.md).

Older profile names remain accepted as deprecated compatibility aliases but are
not part of the public profile API.

## Platforms

| Platform | Status |
|----------|--------|
| Windows x64 | Supported |
| Linux x86_64 | Wheel build configured |
| Raspberry Pi 4/5 ARM64 | Wheel build configured; hardware validation required |
| macOS arm64 | Coming soon |

## Links

- [Python quickstart](https://github.com/rongeld/sky-tracker-sdk/blob/main/docs/quickstart-python.md)
- [Node.js SDK](https://www.npmjs.com/package/@sky-tracker/node)

## Native SDK and platform builds

The [C++ SDK](docs/quickstart-cpp.md) accepts borrowed Gray8, Bgr8, or Rgb8 frames
through an OpenCV-free public header and exports an installed CMake target.
The [Android binding](android/README.md) accepts camera Y-plane buffers, and the
[Jetson build script](packaging/jetson/build.sh) prepares CPU binaries for JetPack 4.
Android and Jetson need validation on their target devices before release.
