Skip to content

optical.hpp

IOptical — a color / optical sensor (pros::Optical) behind the HAL.

This header declares 1 type (10 members).

Extracted from include/shulib/hal/optical.hpp — this page is that header's documentation, reformatted, so it cannot disagree with the code. Prose about how to think about the API lives in the user guide; worked recipes live in the cookbook; this page is the complete, mechanical list of what exists.

Contents

class IOptical

class IOptical

A color / optical sensor behind the HAL — the seam over pros::Optical that game-object color confirmation reads (the M4 scoring-half orient, the Toggle color confirm, intake capture). Every reader's SCALE is fixed by this seam, not by the device: hue in degrees [0, 360), the other three in [0, 1]. An implementation owns whatever vendor rescaling that takes, so no caller ever divides by 255 or wonders which scale it got. Read-only — the vendor's LED, gesture and integration-time controls are not part of this seam.

class, declared at include/shulib/hal/optical.hpp:22.

IOptical::~IOptical

virtual ~IOptical() = default

The polymorphic-base special members, and the exact rule they follow. The virtual destructor is what makes deleting a derived sensor through an IOptical* legal, and user-declaring it costs the two MOVE operations: the move constructor and move assignment are then never implicitly declared, while the COPY pair still is (merely deprecated). So only the two && lines below restore anything. Declaring constructors is in turn what suppresses the implicit default constructor, which is why IOptical() = default; has to be spelled out — without it no derived sensor could be default-constructed. None of this is an invitation to copy a live device: implementations are held by pointer, and copying one would duplicate a port, not a reading.

function, declared at include/shulib/hal/optical.hpp:33.

IOptical::IOptical

IOptical() = default

Covered by the comment on ~IOptical — one comment documents this run of special members.

function, declared at include/shulib/hal/optical.hpp:34.

IOptical::IOptical (overload 2)

IOptical(const IOptical&) = default

Covered by the comment on ~IOptical — one comment documents this run of special members.

function, declared at include/shulib/hal/optical.hpp:35.

IOptical::IOptical (overload 3)

IOptical(IOptical&&) = default

Covered by the comment on ~IOptical — one comment documents this run of special members.

function, declared at include/shulib/hal/optical.hpp:36.

IOptical::operator=

IOptical& operator=(const IOptical&) = default

Covered by the comment on ~IOptical — one comment documents this run of special members.

function, declared at include/shulib/hal/optical.hpp:37.

IOptical::operator= (overload 2)

IOptical& operator=(IOptical&&) = default

Covered by the comment on ~IOptical — one comment documents this run of special members.

function, declared at include/shulib/hal/optical.hpp:38.

IOptical::hue

[[nodiscard]] virtual double hue() const = 0

Detected color hue in degrees, [0, 360). A color, not a heading.

function, declared at include/shulib/hal/optical.hpp:41.

IOptical::saturation

[[nodiscard]] virtual double saturation() const = 0

Color saturation in [0, 1].

function, declared at include/shulib/hal/optical.hpp:44.

IOptical::brightness

[[nodiscard]] virtual double brightness() const = 0

Brightness in [0, 1].

function, declared at include/shulib/hal/optical.hpp:47.

IOptical::proximity

[[nodiscard]] virtual double proximity() const = 0

Proximity in [0, 1] (≈1 = object close to the sensor).

function, declared at include/shulib/hal/optical.hpp:50.

Design commentary, from the header

The header opens with the reasoning behind these shapes. It is reproduced here in full because a reference that only lists signatures teaches nobody why.

The header’s own reasoning — 9 lines 
 IOptical — a color / optical sensor (pros::Optical) behind the HAL. Used for
 game-object color confirmation (master plan §M4: orientToScoringHalf, the Toggle
 color confirm, intake capture).

 hue() is a COLOR hue in degrees [0, 360) — cyclic, but NOT a heading, so it is a
 plain double, never a math::Angle (mixing a color with a spatial angle would be a
 bug). saturation()/brightness()/proximity() are normalized to [0, 1] by the
 hal/pros adapter (proximity ≈ 1 means an object is close).

Last updated 2026-08-15 — published from the main release branch, commit fa545ff. This site tracks releases, so between them it can lag the repository — that lag is deliberate, and it is what keeps the development log off the public site. For the current state of the code, see the repository.