voyant_frame.hpp

Go to the documentation of this file.

// Copyright (c) 2024-2025 Voyant Photonics, Inc.
// All rights reserved.
 
#pragma once
 
#include <carbon_client_ffi.hpp>
#include <cstdint>
#include <iomanip>
#include <optional>
#include <ostream>
#include <sensor_state_display.hpp>
#include <sstream>
#include <string>
#include <utility>
#include <vector>
#include <voyant_types_ffi.hpp>

using PointData = PointDataV1;
static_assert(sizeof(PointData) == 36, "PointDataV1 is frozen at 36 bytes");

inline bool isValidPoint(const PointData& point)
{
    return point.drop_reason == DROP_REASON_VALID;
}

inline bool setPointsXyz(std::vector<PointData>& points, const std::vector<VoyantVec3>& positions)
{
    if (points.size() != positions.size())
    {
        return false;
    }
    if (points.empty())
    {
        return true;
    }
    return voyant_points_set_xyz(points.data(), points.size(), positions.data());
}

class VoyantFrame
{
public:
    VoyantFrame() = default;
 
    const std::vector<PointData>& points() const
    {
        return points_;
    }
    std::vector<PointData>& points()
    {
        return points_;
    }
 
    size_t nPoints() const
    {
        return points_.size();
    }

    size_t nValidPoints() const
    {
        size_t n = 0;
        for (const PointData& point : points_)
        {
            n += isValidPoint(point) ? 1 : 0;
        }
        return n;
    }

    bool carriesState() const
    {
        return meta_.state_provenance == static_cast<uint8_t>(StateProvenance::Measured);
    }

    std::optional<SensorState> sensorState() const
    {
        if (!carriesState())
        {
            return std::nullopt;
        }
        return voyant_frame_sensor_state(&meta_);
    }

    std::optional<HostState> hostState() const
    {
        if (!carriesState())
        {
            return std::nullopt;
        }
        return voyant_frame_host_state(&meta_);
    }

    uint32_t frameIndex() const
    {
        return meta_.frame_index;
    }

    int64_t timestampSeconds() const
    {
        return meta_.timestamp_seconds;
    }

    int32_t timestampNanoseconds() const
    {
        return meta_.timestamp_nanoseconds;
    }

    double timestamp() const
    {
        return static_cast<double>(meta_.timestamp_seconds) + static_cast<double>(meta_.timestamp_nanoseconds) * 1e-9;
    }

    std::string deviceId() const
    {
        char buf[32];
        voyant_frame_device_id(&meta_, buf, sizeof(buf));
        return buf;
    }

    VoyantFrame withPoints(std::vector<PointData> points) const
    {
        // Copy only the metadata: copy-constructing from *this would deep-copy this
        // frame's points just to overwrite them.
        VoyantFrame derived;
        derived.meta_   = meta_;
        derived.points_ = std::move(points);
        return derived;
    }

    struct SyntheticFrameDesc
    {
        ProductId source               = ProductId::Unknown;
        int64_t   timestampSeconds     = 0;
        int32_t   timestampNanoseconds = 0;
        uint32_t  frameIndex           = 0;
    };

    static std::optional<VoyantFrame> synthetic(std::vector<PointData> points, const SyntheticFrameDesc& desc)
    {
        VoyantFrame frame;
        if (!voyant_synthetic_frame_meta(static_cast<uint8_t>(desc.source), desc.timestampSeconds,
                                         desc.timestampNanoseconds, desc.frameIndex, &frame.meta_))
        {
            return std::nullopt;
        }
        frame.points_ = std::move(points);
        return frame;
    }

    // An overload rather than `desc = {}` — GCC rejects brace-init default
    // arguments for nested aggregate types (bug 88165).
    static std::optional<VoyantFrame> synthetic(std::vector<PointData> points)
    {
        return synthetic(std::move(points), SyntheticFrameDesc{});
    }

    struct StatelessFrameDesc
    {
        ProductId source               = ProductId::Unknown;
        uint32_t  serialNumber         = 0;
        int64_t   timestampSeconds     = 0;
        int32_t   timestampNanoseconds = 0;
        uint32_t  frameIndex           = 0;
    };

    static std::optional<VoyantFrame> stateless(std::vector<PointData> points, const StatelessFrameDesc& desc)
    {
        VoyantFrame frame;
        if (!voyant_stateless_frame_meta(static_cast<uint8_t>(desc.source), desc.serialNumber, desc.timestampSeconds,
                                         desc.timestampNanoseconds, desc.frameIndex, &frame.meta_))
        {
            return std::nullopt;
        }
        frame.points_ = std::move(points);
        return frame;
    }

    static std::optional<VoyantFrame> stateless(std::vector<PointData> points)
    {
        return stateless(std::move(points), StatelessFrameDesc{});
    }

    std::optional<VoyantFrame> withSdl(const SdlCommandParams& params) const
    {
        VoyantFrame derived;
        derived.meta_ = meta_;
        if (!voyant_frame_meta_with_sdl(&derived.meta_, params.req_state, params.frame_rate_fps, params.hfov_deg,
                                        params.hfov_center_deg, params.ramp_bandwidth_ghz))
        {
            return std::nullopt;
        }
        derived.points_ = points_;
        return derived;
    }

    std::vector<VoyantVec3> xyz() const
    {
        std::vector<VoyantVec3> out(points_.size());
        if (!points_.empty())
        {
            voyant_points_xyz(points_.data(), points_.size(), out.data());
        }
        return out;
    }

    std::string describe() const;
 
private:
    VoyantFrameMeta toMeta() const
    {
        VoyantFrameMeta meta = meta_;
        meta.n_points        = points_.size();
        return meta;
    }
 
    VoyantFrameMeta        meta_{}; // zeroed: provenance Unknown, i.e. carries no state
    std::vector<PointData> points_;
 
    // The producers fill meta_/points_ directly; keeping that access friend-only
    // means no user code can construct a frame claiming real (Measured) state.
    friend class CarbonClient;
    friend class VoyantPlayback;
    friend class VoyantRecorder;
};

inline std::ostream& operator<<(std::ostream& os, const VoyantFrame& frame)
{
    std::ios_base::fmtflags flags(os.flags());
    std::streamsize         prec = os.precision();
    os << "VoyantFrame(frame_index=" << frame.frameIndex() << ", n_points=" << frame.nPoints()
       << ", n_valid_points=" << frame.nValidPoints() << std::fixed << std::setprecision(6)
       << ", timestamp=" << frame.timestamp() << ", device_id=" << frame.deviceId() << ")";
    os.flags(flags);
    os.precision(prec);
    return os;
}
 
inline std::string VoyantFrame::describe() const
{
    std::ostringstream out;
    out << *this;
    if (!carriesState())
    {
        out << "\n  NO SENSOR STATE — none was recorded for this frame."
               "\n  Points are real; health, calibration, SDL and time-sync are not"
               "\n  available, and device identity and timestamps may be unset.";
        return out.str();
    }
    const SensorState state = *sensorState();
    out << "\n  " << state.device << "\n  " << state.sdl << "\n  " << *hostState();
    return out.str();
}