HiveVision

Camera-based detection, target filtering, field positioning, and Weaver path routing library for FTC robots.

HiveVision turns Limelight 3A neural network detections into absolute field coordinates and generates optimal path routes for autonomous navigation. It is built natively for FTC game elements (such as POLLEN, NECTAR_RED, NECTAR_BLUE) using Limelight 3A SSD detectors and integrates seamlessly with Pedro Pathing and Marrow Weaver.

Docs & Maven repository: sidhuharjas.github.io/hvtest

---

Modules

HiveVision is split into two lightweight artifacts:

Artifact	Description	Dependencies
org.hivevisionftc:core	Perception pipeline, Limelight 3A integration, detection filtering, sorting, and camera-to-field coordinate projection.	FTC SDK (RobotCore, Hardware)
org.hivevisionftc:weaver	Optional path routing module that converts detection lists into obstacle-avoiding Marrow Weaver bezier paths.	:core, Marrow core

---

Installation

Artifacts are hosted on GitHub Pages — no Maven Central account or extra mirrors needed.

Add the repository and dependencies to your TeamCode/build.gradle:

repositories {
    maven { url = uri("https://sidhuharjas.github.io/hvtest") }
}

dependencies {
    // Core vision module
    implementation 'org.hivevisionftc:core:1.0.0'

    // Optional: Marrow Weaver route planning
    implementation 'org.hivevisionftc:weaver:1.0.0'
}

Step-by-step setup, calibration, and usage: sidhuharjas.github.io/hvtest

---

Quickstart

1. Configure and Initialize Vision

// Define camera geometry and detection thresholds
VisionConfig config = new VisionConfig()
        .camPitchDeg(25.0)          // Camera tilt angle below horizontal
        .camHeight(9.2)             // Camera lens height above floor (inches)
        .ballHeight(3.0)            // Game element center height above floor (inches)
        .camXOffset(4.0)            // Camera forward offset from robot center (inches)
        .camYOffset(0.0)            // Camera left offset from robot center (inches)
        .minConfidence(0.44)        // Minimum detection confidence threshold
        .maxStalenessMs(120)        // Max allowed data staleness (ms)
        .pipeline(3)                // Limelight pipeline index
        .pollingRateHz(150);        // Camera polling rate

// Initialize Limelight source & vision session
Limelight3A limelight = hardwareMap.get(Limelight3A.class, "limelight");
HiveVision vision = new HiveVision(limelight, config);

// Optional: restrict which classes to chase (default = all three)
vision.setAllowedClasses(
        BiobuzzClasses.POLLEN,          // neutral yellow pollen
        BiobuzzClasses.NECTAR_RED,      // alliance red nectar
        BiobuzzClasses.NECTAR_BLUE);    // alliance blue nectar

2. Fetch and Query Detections

// Fetch detections and project them to field coordinates given robot's current pose
FieldPose robotPose = new FieldPose(follower.pose().x(), follower.pose().y(), follower.pose().heading());

// Query the closest detected element
Detection target = vision.detections()
        .fetch(robotPose)
        .sortByDistance()
        .getClosest();

if (target != null) {
    telemetry.addData("Target Class", target.getBallClass());
    telemetry.addData("Target Field X", target.getX());
    telemetry.addData("Target Field Y", target.getY());
}

3. Generate Weaver Bezier Paths (Auto Routing)

// Convert detected elements directly into an obstacle-avoiding Weaver path result
PathResult path = vision.detections()
        .fetch(robotPose)
        .sortByDistance()
        .with(WeaverRoute.fromFetchPose()
                .avoid(new CircleZone(new Point(72, 72), 18.0)) // Add obstacle zones
                .maxTargets(4));                                // Limit path targets

if (path != null) {
    follower.follow(PedroPathingConverter.toPath(path)); // import com.skeletonarmy.marrow.weaver.PedroPathingConverter
}

---

Running the Examples

Two ready-to-run OpModes live in docs/examples/:

OpMode	Driver Station name	What it does
AutoBallHuntOpMode	HiveVision Weaver Auto	One-shot autonomous: detect, build a Weaver route through the closest 2 targets, drive it.
ManualBallChaseOpMode	HiveVision Loop with Obstacles	Detection loop for the whole match; re-plans around an obstacle when the robot is idle.

To run one:

1. Copy that OpMode plus SampleFollowerFactory.java into your TeamCode module (both files already declare package org.firstinspires.ftc.teamcode).
2. Adjust the VisionConfig values for your camera mount, and make sure the Limelight is configured under the hardware name "limelight".
3. Build and deploy TeamCode to the robot as usual.
4. On the Driver Station, select Autonomous → HiveVision Weaver Auto (or the loop variant), power on the Limelight, and press start.

Telemetry reports the closest element class, field X/Y, and route status. If it says "No targets detected", check the Limelight pipeline index and that the game elements are in view.

---

Calibration

Accurate distance estimation and field projection require proper physical measurement of your camera mounting geometry. Refer to docs/calibration.md for step-by-step measurement procedures and coordinate system conventions.

Config Method	Description
camPitchDeg(double)	Downward tilt angle of the camera optic axis in degrees below horizontal.
camHeight(double)	Distance from floor to center of camera lens (inches).
ballHeight(double)	Distance from floor to center of target game element (inches).
camXOffset(double)	Forward (+X) offset of camera lens relative to robot center (inches).
camYOffset(double)	Left (+Y) offset of camera lens relative to robot center (inches, negative for right).
minConfidence(double)	Confidence threshold for accepting detections (0.0 to 1.0).
maxStalenessMs(long)	Maximum time in milliseconds before detection data is discarded.

---

Documentation & Examples

• sidhuharjas.github.io/hvtest — Setup guide, quickstart, and calibration summary.
• MODULES.md — Complete API and class reference for :core and :weaver.
• calibration.md — Procedure for measuring camera offsets, pitch angles, and understanding coordinate frames.
• weaver/README.md — Quick guide to using the WeaverRoute extension.
• docs/examples/ — Sample OpModes (AutoBallHuntOpMode, ManualBallChaseOpMode) demonstrating integration with Pedro Pathing — see Running the Examples.

---

Building and Testing

# Run unit test suites (JVM-based, no camera required)
./gradlew test

# Format code according to Spotless Java rules
./gradlew spotlessApply

# Check code formatting
./gradlew spotlessCheck

# Build release library archives (AARs, sources, javadocs)
./gradlew assembleRelease

---

Publishing

Releases are published to the GitHub Pages Maven repository at sidhuharjas.github.io/hvtest by the Publish to Pages Maven repo workflow. It builds the AARs, pushes them to the gh-pages branch, and the docs site along with them.

To cut a release:

1. Bump version in build.gradle.kts.
2. Push a v* tag (git tag v1.1.0 && git push --tags), or run the workflow manually from the Actions tab.

Local testing uses the Deployer plugin configured in build.gradle.kts:

Gradle Task	Description
./gradlew deployLocal	Publishes artifacts to Maven Local (~/.m2) for testing.
./gradlew deployNexusSnapshot	Publishes snapshot builds to Sonatype Nexus.
./gradlew deployCentralPortal	Publishes release builds to Maven Central.

---

License

MIT License. See LICENSE for details.