render_view.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2025 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
 
#pragma once
 
// Headless render-to-image (#294).
//
// Renders the contents of a .rux project to an in-memory image without a
// display server. The backend is VTK's offscreen render window: the flake's
// VTK is built with VTK_OPENGL_HAS_EGL, and VTK transparently falls back from
// vtkXOpenGLRenderWindow to vtkEGLRenderWindow when no X/Wayland session is
// reachable, so `env -u DISPLAY rux render ...` renders on the GPU exactly as
// it would with a session attached.
//
// Keep this header light (STANDARDS §2): cv::Mat and ProjectDB are
// forward-declared, and no VTK header is exposed to consumers.
 
#include <array>
#include <cstdint>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <vector>
 
namespace cv {
class Mat;
} // namespace cv
 
namespace reusex {
 
class ProjectDB;
 
namespace visualize {

enum class Layer {
  cloud,      
  labels,     
  planes,     
  rooms,      
  instances,  
  mesh,       
  components, 
  frustums,   
  panoramas,  
};

std::optional<Layer> layer_from_string(std::string_view name);

std::string_view to_string(Layer layer);

const std::vector<Layer> &all_layers();

enum class ViewPreset {
  top,
  plan,
  front,
  orbit,
  explicit_camera,
};

std::string_view to_string(ViewPreset view);

std::optional<ViewPreset> view_preset_from_string(std::string_view name);

struct CameraSpec {
  std::array<double, 16> pose{1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1};
  double fx = 0.0; 
  double fy = 0.0; 
  double cx = 0.0; 
  double cy = 0.0; 
};

inline constexpr double kDefaultCutHeightM = 1.2;

inline constexpr double kDefaultCutBboxFraction = 0.45;

inline constexpr double kHorizontalNormalZ = 0.95;

struct InstanceHighlight {
  std::string cloud_name = "instances";
  std::uint32_t instance_id = 0;
};

struct RenderOptions {
  std::vector<Layer> layers{Layer::cloud};

  std::string cloud_name = "cloud";
  std::string mesh_name = "mesh";
 
  ViewPreset view = ViewPreset::top;

  int orbit_count = 8;
  int orbit_index = 0;
  double orbit_elevation_deg = 25.0;

  std::optional<CameraSpec> camera;

  bool cut = false;

  std::optional<double> cut_height;
 
  int width = 1600;
  int height = 1200;

  std::array<double, 3> background{0.11, 0.12, 0.14};

  double point_size = 2.0;

  double margin = 1.08;

  std::optional<InstanceHighlight> highlight;
};

class OffscreenGlUnavailable : public std::runtime_error {
    public:
  using std::runtime_error::runtime_error;
};

cv::Mat render_view(const ProjectDB &db, const RenderOptions &opts);

CameraSpec camera_from_sensor_frame(const ProjectDB &db, int node_id, int width,
                                    int height);
 
} // namespace visualize
} // namespace reusex