Stitches multiple camera images into a single spherical panorama using Basalt calibration data. More...

#include <panoweave.hpp>

Public Member Functions
	Stitcher ()
	Constructs an empty Stitcher object.
	Stitcher (const std::string &calibration_filepath)
	Constructs a Stitcher object with the specified calibration file.
	Stitcher (const std::string &calibration_filepath, ScalarT depth)
	Constructs a Stitcher object with the specified calibration file and uniform depth.
	Stitcher (const std::string &calibration_filepath, const cv::Mat &depth)
	Constructs a Stitcher object with the specified calibration file and per-point depth.
	~Stitcher ()
	Destructor for the Stitcher class.
void	loadCalibration (const std::string &calibration_filepath)
	Loads camera calibration data from the specified file.
const basalt::Calibration< ScalarT > &	calibration () const
	Returns a read-only reference to the calibration data.
void	setDepth (ScalarT depth)
	Sets a uniform depth for the panorama.
void	setDepth (const cv::Mat &depth)
	Sets a per-point depth map for the panorama.
cv::Size	resolution () const
	Get the current output resolution for the panorama.
cv::Size	resolution (const cv::Size &resolution)
	Set the output resolution for the panorama.
cv::Size	resolution (int width, int height)
	Set the output resolution for the panorama.
int	width () const
	Get the current output width for the panorama.
int	width (int width)
	Set the output width for the panorama.
int	height () const
	Get the current output height for the panorama.
int	height (int height)
	Set the output height for the panorama.
CvFovT	fov () const
	Get the current field of view (FOV) for the panorama.
CvFovT	fov (CvFovT fov)
	Set the field of view (FOV) for the panorama.
CvFovT	fov (ScalarT fov_x, ScalarT fov_y)
	Set the field of view (FOV) for the panorama.
ScalarT	fovX () const
	Get the current horizontal field of view (FOV) for the panorama.
ScalarT	fovX (ScalarT fov)
	Set the horizontal field of view (FOV) for the panorama.
ScalarT	fovY () const
	Get the current vertical field of view (FOV) for the panorama.
ScalarT	fovY (ScalarT fov)
	Set the vertical field of view (FOV) for the panorama.
ScalarT	vignetteThreshold () const
	Get the current vignette threshold.
ScalarT	vignetteThreshold (ScalarT threshold)
	Set the vignette threshold used to generate vignette maps.
bool	useMaskAsVignette () const
	Gets whether the mask is used as vignette.
bool	useMaskAsVignette (bool use)
	Sets whether to use the mask as vignette.
CvAffine3T	transform () const
	Get the current transformation from body to calibration coordinate system.
CvAffine3T	transform (const CvAffine3T &transform)
	Set the transformation from body to calibration coordinate system.
CvAffine3T	transform (const CvAffine3T::Mat4 &affine)
	Set the transformation using an affine matrix.
CvAffine3T	transform (const CvAffine3T::Mat3 &rotation, const CvAffine3T::Vec3 &translation=CvAffine3T::Vec3(0, 0, 0))
	Set the transformation using rotation matrix and translation vector.
CvAffine3T	transform (const CvAffine3T::Vec3 &rotation, const CvAffine3T::Vec3 &translation=CvAffine3T::Vec3(0, 0, 0))
	Set the transformation using a rotation vector and translation vector.
void	stitch (const std::vector< cv::Mat > &images, const std::vector< ScalarT > &exposure, cv::Mat &pano)
	Stitches the provided input images into a single panoramic image.
void	stitch (const std::vector< cv::Mat > &images, cv::Mat &pano)
	Stitches the provided input images into a single panoramic image.
void	stitch (const std::vector< cv::Mat > &images, const std::vector< ScalarT > &exposure, ScalarT depth, cv::Mat &pano)
	Stitches the provided input images into a single panoramic image.
void	stitch (const std::vector< cv::Mat > &images, const std::vector< ScalarT > &exposure, const cv::Mat &depth, cv::Mat &pano)
	Stitches the provided input images into a single panoramic image.
bool	buildInternals ()
	Builds all necessary internal data structures required for stitching.

Private Member Functions
bool	buildMaps ()
	Builds the lookup tables and initial proximity-based weights.
void	buildVignettes ()
	Builds the vignette maps.
void	buildMask ()
	Builds the masks and finalizes the weights.
void	buildMirrors ()
	Builds the vignette map and weight mirrors for multi-channel images.

Detailed Description

Stitches multiple camera images into a single spherical panorama using Basalt calibration data.

The Stitcher supports setting resolution, field of view, depth, and transformation of the spherical camera. Depth values can be provided as a uniform scalar or a per-pixel depth map to cover simple or complex use cases. Exposure times of the input images can optionally be used to adjust the input images to a common exposure. Images with one (mono), three (BGR, RGB), or four (BGRA, RGBA) channels are supported without extra configuration.

Note: Internal data structures are built lazily, i.e., only when required at the beginning of stitching. This avoids unnecessary computation when multiple parameters are changed before stitching.

Example usage:

panoweave::Stitcher stitcher("calibration.json");
stitcher.resolution(2160, 1080);
stitcher.setDepth(5.0f);
cv::Mat pano;
stitcher.stitch(images, exposures, pano);

Constructor & Destructor Documentation

◆ Stitcher() [1/4]

panoweave::Stitcher::Stitcher ( )

Constructs an empty Stitcher object.

Initializes an empty Stitcher object. Calibration data must be loaded, resolution set, and depth defined before stitching operations can be performed.

◆ Stitcher() [2/4]

panoweave::Stitcher::Stitcher ( const std::string & calibration_filepath )

Constructs a Stitcher object with the specified calibration file.

Loads camera calibration data from the given file path.

Parameters

calibration_filepath Path to the camera calibration data file.

Exceptions

std::runtime_error If the file cannot be opened or the data is invalid.

See also: loadCalibration

◆ Stitcher() [3/4]

panoweave::Stitcher::Stitcher	(	const std::string &	calibration_filepath,
		ScalarT	depth )

Constructs a Stitcher object with the specified calibration file and uniform depth.

Loads camera calibration and sets a uniform depth value.

Parameters

calibration_filepath	Path to the camera calibration data file.
depth	Uniform depth value.

Exceptions

std::runtime_error If the file cannot be opened or the data is invalid.

See also: loadCalibration, setDepth

◆ Stitcher() [4/4]

panoweave::Stitcher::Stitcher	(	const std::string &	calibration_filepath,
		const cv::Mat &	depth )

Constructs a Stitcher object with the specified calibration file and per-point depth.

Loads camera calibration and sets a per-point depth map.

Parameters

calibration_filepath	Path to the camera calibration data file.
depth	Per-point depth map.

Exceptions

std::runtime_error If the file cannot be opened or the data is invalid.

See also: loadCalibration, setDepth

◆ ~Stitcher()

panoweave::Stitcher::~Stitcher ( )

Destructor for the Stitcher class.

Uses the default destructor.

Member Function Documentation

◆ buildInternals()

bool panoweave::Stitcher::buildInternals ( )

Builds all necessary internal data structures required for stitching.

Calls the individual build functions for maps, vignettes, mask, and mirrors as needed.

Note: This function is called internally before stitching if any internal data structures need to be rebuilt.

Returns: True if all internal data structures were built successfully, false otherwise.

◆ buildMaps()

bool panoweave::Stitcher::buildMaps ( )

private

Builds the lookup tables and initial proximity-based weights.

Generates a spherical point cloud based on the current resolution and field of view, transforms the points using the current transformation, and builds the mapping tables and initial proximity-based weights in the calibration.

Note: Triggers mask rebuild.

Returns: true If the mapping tables were built successfully.; false If there was an error building the mapping tables.

◆ buildMask()

void panoweave::Stitcher::buildMask ( )

private

Builds the masks and finalizes the weights.

Generates masks from vignette maps and applies them to normalize and combine the proximity-based weights. Updates the vignette maps if the mask is used as vignette.

Note: Triggers mirror rebuild.

◆ buildMirrors()

void panoweave::Stitcher::buildMirrors ( )

private

Builds the vignette map and weight mirrors for multi-channel images.

Generates multi-channel versions of the vignette maps and weights to support multi-channel images.

◆ buildVignettes()

void panoweave::Stitcher::buildVignettes ( )

private

Builds the vignette maps.

Generates vignette maps based on the current vignette threshold and calibration data.

Note: Triggers mask and mirror rebuild.

◆ calibration()

const basalt::Calibration< ScalarT > & panoweave::Stitcher::calibration ( ) const

Returns a read-only reference to the calibration data.

Returns: Calibration data used for stitching.

◆ fov() [1/3]

CvFovT panoweave::Stitcher::fov ( ) const

Get the current field of view (FOV) for the panorama.

Returns: The current FOV.

◆ fov() [2/3]

CvFovT panoweave::Stitcher::fov ( CvFovT fov )

Set the field of view (FOV) for the panorama.

The FOV must be in the range (0, 2*Pi] for horizontal and (0, Pi] for vertical.

Note: Requires rebuilding the mapping tables.

Parameters

fov	Desired FOV.

Returns: The set FOV.

◆ fov() [3/3]

CvFovT panoweave::Stitcher::fov	(	ScalarT	fov_x,
		ScalarT	fov_y )

Set the field of view (FOV) for the panorama.

Overload accepting horizontal and vertical FOV as separate parameters.

Note: Requires rebuilding the mapping tables.

Parameters

fov_x	Desired horizontal FOV.
fov_y	Desired vertical FOV.

Returns: The set FOV.

◆ fovX() [1/2]

ScalarT panoweave::Stitcher::fovX ( ) const

Get the current horizontal field of view (FOV) for the panorama.

Returns: The current horizontal FOV.

◆ fovX() [2/2]

ScalarT panoweave::Stitcher::fovX ( ScalarT fov )

Set the horizontal field of view (FOV) for the panorama.

The horizontal FOV must be in the range (0, 2*Pi].

Note: Requires rebuilding the mapping tables.

Parameters

fov	Desired horizontal FOV.

Returns: The set horizontal FOV.

◆ fovY() [1/2]

ScalarT panoweave::Stitcher::fovY ( ) const

Get the current vertical field of view (FOV) for the panorama.

Returns: The current vertical FOV.

◆ fovY() [2/2]

ScalarT panoweave::Stitcher::fovY ( ScalarT fov )

Set the vertical field of view (FOV) for the panorama.

The vertical FOV must be in the range (0, Pi].

Note: Requires rebuilding the mapping tables.

Parameters

fov	Desired vertical FOV.

Returns: The set vertical FOV.

◆ height() [1/2]

int panoweave::Stitcher::height ( ) const

Get the current output height for the panorama.

Returns: The current height.

◆ height() [2/2]

int panoweave::Stitcher::height ( int height )

Set the output height for the panorama.

Note: Requires rebuilding the mapping tables.

Parameters

height Desired height.

Returns: The set height.

◆ loadCalibration()

void panoweave::Stitcher::loadCalibration ( const std::string & calibration_filepath )

Loads camera calibration data from the specified file.

Reads calibration parameters from a Basalt calibration.json file.

Note: Requires rebuilding of all internal data structures.

Parameters

calibration_filepath Path to the camera calibration data file.

Exceptions

std::runtime_error If the file cannot be opened or the data is invalid.

◆ resolution() [1/3]

cv::Size panoweave::Stitcher::resolution ( ) const

Get the current output resolution for the panorama.

Returns: The current resolution.

◆ resolution() [2/3]

cv::Size panoweave::Stitcher::resolution ( const cv::Size & resolution )

Set the output resolution for the panorama.

Note: Requires rebuilding the mapping tables.

Parameters

resolution Desired resolution.

Returns: The set resolution.

◆ resolution() [3/3]

cv::Size panoweave::Stitcher::resolution	(	int	width,
		int	height )

Set the output resolution for the panorama.

Overload accepting width and height as separate parameters.

Note: Requires rebuilding the mapping tables.

Parameters

width	Desired width.
height	Desired height.

Returns: The set resolution.

◆ setDepth() [1/2]

void panoweave::Stitcher::setDepth ( const cv::Mat & depth )

Sets a per-point depth map for the panorama.

The depth map provides depth information for each point in the panorama. Its resolution must match the output resolution of the panorama.

Note: Requires rebuilding the mapping tables.

Parameters

depth Per-point depth map.

◆ setDepth() [2/2]

void panoweave::Stitcher::setDepth ( ScalarT depth )

Sets a uniform depth for the panorama.

Uses the same depth value for all points in the panorama.

Note: Requires rebuilding the mapping tables.

Parameters

depth Uniform depth value.

◆ stitch() [1/4]

void panoweave::Stitcher::stitch	(	const std::vector< cv::Mat > &	images,
		const std::vector< ScalarT > &	exposure,
		const cv::Mat &	depth,
		cv::Mat &	pano )

Stitches the provided input images into a single panoramic image.

Overload for stitching with a per-point depth map.

Warning: Triggers rebuild of mapping tables, making it significantly slower than other stitch() overloads.

Parameters

images	Vector of input images to be stitched.
exposure	Vector of exposure values corresponding to each input image.
depth	Per-point depth map to be used for all points.
pano	Output panoramic image.

See also: setDepth

◆ stitch() [2/4]

void panoweave::Stitcher::stitch	(	const std::vector< cv::Mat > &	images,
		const std::vector< ScalarT > &	exposure,
		cv::Mat &	pano )

Stitches the provided input images into a single panoramic image.

Exposure values are used to correct the brightness of each input image and adjust the overall exposure of the panorama. Internal data structures are built or rebuilt as necessary before stitching.

Parameters

images	Vector of input images to be stitched.
exposure	Vector of exposure values corresponding to each input image.
pano	Output panoramic image.

◆ stitch() [3/4]

void panoweave::Stitcher::stitch	(	const std::vector< cv::Mat > &	images,
		const std::vector< ScalarT > &	exposure,
		ScalarT	depth,
		cv::Mat &	pano )

Stitches the provided input images into a single panoramic image.

Overload for stitching with a uniform depth value.

Warning: Triggers rebuild of mapping tables, making it significantly slower than other stitch() overloads.

Parameters

images	Vector of input images to be stitched.
exposure	Vector of exposure values corresponding to each input image.
depth	Uniform depth value to be used for all points.
pano	Output panoramic image.

See also: setDepth

◆ stitch() [4/4]

void panoweave::Stitcher::stitch	(	const std::vector< cv::Mat > &	images,
		cv::Mat &	pano )

Stitches the provided input images into a single panoramic image.

Overload for stitching without exposure correction.

Parameters

images	Vector of input images to be stitched.
pano	Output panoramic image.

◆ transform() [1/5]

CvAffine3T panoweave::Stitcher::transform ( ) const

Get the current transformation from body to calibration coordinate system.

Returns: The current transformation.

◆ transform() [2/5]

CvAffine3T panoweave::Stitcher::transform ( const CvAffine3T & transform )

Set the transformation from body to calibration coordinate system.

This transformation is applied to spherical points before projecting them into camera views. The Basalt calibration coordinate system is either the IMU or the first camera coordinate system, depending on the calibration type.

Note: Requires rebuilding the mapping tables.

Parameters

transform Desired transformation.

Returns: The set transformation.

◆ transform() [3/5]

CvAffine3T panoweave::Stitcher::transform	(	const CvAffine3T::Mat3 &	rotation,
		const CvAffine3T::Vec3 &	translation = CvAffine3T::Vec3(0, 0, 0) )

Set the transformation using rotation matrix and translation vector.

Note: Requires rebuilding the mapping tables.

Parameters

rotation	Desired rotation matrix.
translation	Desired translation vector.

Returns: The set transformation.

◆ transform() [4/5]

CvAffine3T panoweave::Stitcher::transform ( const CvAffine3T::Mat4 & affine )

Set the transformation using an affine matrix.

Note: Requires rebuilding the mapping tables.

Parameters

affine Desired affine transformation matrix.

Returns: The set transformation.

◆ transform() [5/5]

CvAffine3T panoweave::Stitcher::transform	(	const CvAffine3T::Vec3 &	rotation,
		const CvAffine3T::Vec3 &	translation = CvAffine3T::Vec3(0, 0, 0) )

Set the transformation using a rotation vector and translation vector.

Note: Requires rebuilding the mapping tables.

Parameters

rotation	Desired rotation vector (axis-angle, Rodrigues).
translation	Desired translation vector.

Returns: The set transformation.

◆ useMaskAsVignette() [1/2]

bool panoweave::Stitcher::useMaskAsVignette ( ) const

Gets whether the mask is used as vignette.

Returns: True if the mask is used as vignette, false otherwise.

◆ useMaskAsVignette() [2/2]

bool panoweave::Stitcher::useMaskAsVignette ( bool use )

Sets whether to use the mask as vignette.

If set to true, the mask will replace the vignette maps. This is useful when vignette correction is not desired (for example, if vignetting calibration quality is insufficient), and the mask should define valid pixel regions instead.

Note: Requires rebuilding the mask or vignette maps depending on the value.

Parameters

use	True to use the mask as vignette, false otherwise.

Returns: The set value.

◆ vignetteThreshold() [1/2]

ScalarT panoweave::Stitcher::vignetteThreshold ( ) const

Get the current vignette threshold.

Returns: The current vignette threshold.

◆ vignetteThreshold() [2/2]

ScalarT panoweave::Stitcher::vignetteThreshold ( ScalarT threshold )

Set the vignette threshold used to generate vignette maps.

The vignette maps are used to compensate for lens vignetting in input images. Values should be in the range [0.0, 1.0]. A lower threshold means pixels farther from the center are considered valid.

Note: Requires rebuilding the vignette maps.

Parameters

threshold Desired vignette threshold.

Returns: The set vignette threshold.

◆ width() [1/2]

int panoweave::Stitcher::width ( ) const

Get the current output width for the panorama.

Returns: The current width.

◆ width() [2/2]

int panoweave::Stitcher::width ( int width )

Set the output width for the panorama.

Note: Requires rebuilding the mapping tables.

Parameters

width Desired width.

Returns: The set width.

The documentation for this class was generated from the following file:

include/panoweave.hpp

Public Member Functions

Private Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Stitcher() [1/4]

◆ Stitcher() [2/4]

◆ Stitcher() [3/4]

◆ Stitcher() [4/4]

◆ ~Stitcher()

Member Function Documentation

◆ buildInternals()

◆ buildMaps()

◆ buildMask()

◆ buildMirrors()

◆ buildVignettes()

◆ calibration()

◆ fov() [1/3]

◆ fov() [2/3]

◆ fov() [3/3]

◆ fovX() [1/2]

◆ fovX() [2/2]

◆ fovY() [1/2]

◆ fovY() [2/2]

◆ height() [1/2]

◆ height() [2/2]

◆ loadCalibration()

◆ resolution() [1/3]

◆ resolution() [2/3]

◆ resolution() [3/3]

◆ setDepth() [1/2]

◆ setDepth() [2/2]

◆ stitch() [1/4]

◆ stitch() [2/4]

◆ stitch() [3/4]

◆ stitch() [4/4]

◆ transform() [1/5]

◆ transform() [2/5]

◆ transform() [3/5]

◆ transform() [4/5]

◆ transform() [5/5]

◆ useMaskAsVignette() [1/2]

◆ useMaskAsVignette() [2/2]

◆ vignetteThreshold() [1/2]

◆ vignetteThreshold() [2/2]

◆ width() [1/2]

◆ width() [2/2]