PoSDK Core Data Types

This document provides detailed information about various core data types used in PoSDK, covering fundamental types, camera models, features and matching, tracks and observations, pose representation, and other key concepts. These types form the fundamental data structures of the entire PoSDK system.

Modular File Structure

PoSDK adopts a modular type system design for better code organization and maintenance.

File Organization

types/
├── types.hpp              # Main entry file, contains complex global pose types
├── base.hpp/cpp           # Fundamental types and environment variable management
├── camera_model.hpp/cpp   # Camera model related types and implementation
├── features.hpp/cpp       # Feature detection and management related types
├── matches.hpp/cpp        # Matching relationships and bearing vector types
├── tracks.hpp/cpp         # Track observation and management related types
├── relative_poses.hpp/cpp # Relative pose and relative rotation types
├── global_poses.hpp/cpp   # Global pose fundamental types and estimation state
├── world_3dpoints.hpp/cpp # 3D point cloud and world coordinate point information
└── image.hpp              # Image related type definitions

Module Responsibilities

Module	Main Content
`base`	Fundamental Types, Method Configuration
`camera_model`	Camera Intrinsics, Distortion Model, Camera Set Management
`features`	Feature Points, Feature Descriptors, Image Feature Management
`matches`	Feature Matching, Bearing Vectors, Geometric Transform Utilities
`tracks`	Track Observations, 3D Point Management, Normalization Processing
`relative_poses`	Relative Pose, Relative Rotation, Accuracy Assessment
`global_poses`	Global Pose Fundamental Types, Pose Format, Estimation State Management
`world_3dpoints`	3D Point Cloud, World Coordinate Point Information, Accuracy Assessment
`types.hpp`	Complex Global Pose Classes, Similarity Transform, Unified Management

Quick Navigation

Fundamental Types (types/base.hpp)

Fundamental Identifier Types

Type Alias Definitions:

Type Alias	Actual Type	Default Value	Purpose
`Ptr<T>`	`std::shared_ptr<T>`	-	Smart pointer type template, provides automatic memory management
`IndexT`	`std::uint32_t`	0	Generic index type for various index identifiers (max value: 4,294,967,295)
`ViewId`	`std::uint32_t`	0	View identifier type for identifying camera views
`PtsId`	`std::uint32_t`	0	Point/track identifier type for identifying 3D points or feature tracks
`Size`	`std::uint32_t`	0	Size type for representing sizes, counts, etc.

Eigen Mathematical Types

Type Alias Definitions:

Type Alias	Actual Type	Default Value	Purpose
`SpMatrix`	`Eigen::SparseMatrix<double>`	-	Sparse matrix type for large sparse linear systems
`Matrix3d`	`Eigen::Matrix3d`	Zero matrix	3×3 double precision matrix for rotation matrices and other transforms
`Vector3d`	`Eigen::Vector3d`	Zero vector	3D double precision vector for 3D coordinates and vectors
`Vector2d`	`Eigen::Vector2d`	Zero vector	2D double precision vector for image coordinates and planar vectors
`Vector2f`	`Eigen::Vector2f`	Zero vector	2D single precision vector for memory-sensitive 2D operations
`VectorXd`	`Eigen::VectorXd`	Zero vector	Dynamic size double precision vector for variable length data
`RowVectorXd`	`Eigen::RowVectorXd`	Zero vector	Dynamic size row vector for matrix operations
`MatrixXd`	`Eigen::MatrixXd`	Zero matrix	Dynamic size matrix for arbitrary size matrix operations

Method Configuration Types

Type Alias Definitions:

Type Alias	Actual Type	Default Value	Purpose
`MethodType`	`std::string`	“”	Method type name, such as “SIFT”, “ORB”, etc.
`MethodParams`	`std::string`	“”	Method parameter name, such as “nfeatures”, “threshold”, etc.
`ParamsValue`	`std::string`	“”	Parameter value type, stored as string
`MethodOptions`	`std::unordered_map<MethodParams, ParamsValue>`	Empty map	All parameter configuration for a single method
`MethodsConfig`	`std::unordered_map<MethodType, MethodOptions>`	Empty map	Configuration collection for all methods

Data Package Types

Type Alias Definitions:

Type Alias	Actual Type	Default Value	Purpose
`DataType`	`std::string`	“”	Data type identifier for key names in data packages
`DataPtr`	`std::shared_ptr<DataIO>`	nullptr	Data pointer type, smart pointer to data IO object
`Package`	`std::unordered_map<DataType, DataPtr>`	Empty map	Basic data package type, key-value pair mapping container
`DataPackagePtr`	`std::shared_ptr<DataPackage>`	nullptr	Data package smart pointer type

Camera Model (types/camera_model.hpp)

The camera model system provides complete camera parameter management, supporting intelligent access for single and multi-camera configurations.

Core Features and Usage Patterns

PIMPL Design Pattern:

Binary Compatibility: Uses PIMPL (Pointer to Implementation) pattern to hide implementation details, providing stable ABI
Extensibility: Easy to add new camera models and calibration methods without affecting client code
Data Encapsulation: Private member variables hidden through std::unique_ptr, improving data security
Memory Alignment: Uses EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro to ensure correct alignment of Eigen types

Intelligent Access Mechanism:

Single Camera Mode: All views share the same intrinsics, any view_id returns the same model
Multi-Camera Mode: Each view corresponds to independent intrinsics, accessed by view_id index
Automatic Recognition: System automatically selects access mode based on number of models

Typical Usage Examples

Basic Camera Model Creation and Configuration

using namespace PoSDK::types;

// Create camera model collection
CameraModels cameras;

// Single camera configuration (recommended for calibration scenarios)
CameraModel single_camera;
single_camera.SetCameraIntrinsics(800.0, 800.0, 320.0, 240.0, 640, 480);
cameras.push_back(single_camera);

Intelligent Access to Camera Intrinsics (Recommended Approach)

ViewId view_id = 1;

// Intelligent index access (returns nullptr on failure)
const CameraModel* camera = cameras[view_id];  // Recommended primary access method
if (camera) {
    // Get intrinsic matrix (efficient version)
    Matrix3d K;
    camera->GetKMat(K);

    // Get intrinsic matrix (convenient version)
    Matrix3d K_conv = camera->GetKMat();

    // Access parameters through accessor methods (recommended approach)
    const auto& intrinsics = camera->GetIntrinsics();
    double fx = intrinsics.GetFx();
    double cy = intrinsics.GetCy();
    uint32_t width = intrinsics.GetWidth();
    uint32_t height = intrinsics.GetHeight();
} else {
    // Handle access failure
}

Multi-Camera Configuration Example

// Multi-camera mode: each view has independent intrinsics
CameraModels multi_cameras;
for (ViewId i = 0; i < 3; ++i) {
    CameraModel camera;
    // Use method 4: complete parameter setting including image size
    camera.SetCameraIntrinsics(800.0 + i*50, 800.0, 320.0, 240.0, 640, 480);
    multi_cameras.push_back(camera);
}

// Access specific camera: returns pointer, need to check nullptr
const CameraModel* cam2 = multi_cameras[2];
if (cam2) {
    // Use parameters from the 3rd camera
    Matrix3d K = cam2->GetKMat();
}

Coordinate Conversion and Distortion Handling

const CameraModel* camera = cameras[view_id];
if (camera) {
    // Pixel coordinate and normalized coordinate conversion
    Vector2d pixel(100.0, 200.0);
    Vector2d normalized = camera->PixelToNormalized(pixel);
    Vector2d back_to_pixel = camera->NormalizedToPixel(normalized);

    // Configure distortion parameters
    std::vector<double> radial_dist = {-0.1, 0.05, -0.01};  // k1, k2, k3
    std::vector<double> tangential_dist = {};  // No tangential distortion
    camera->SetDistortionParams(DistortionType::RADIAL_K3, radial_dist, tangential_dist);

    // Set camera metadata information
    camera->SetCameraInfo("Canon", "EOS 5D", "123456789");
}

`DistortionType`

Camera distortion type enumeration supporting multiple distortion models

Enumeration Definitions:

Type	Definition	Default Value	Purpose
`NO_DISTORTION`	No distortion enumeration value	-	Ideal pinhole camera model, no lens distortion
`RADIAL_K1`	First-order radial distortion enumeration value	-	Simple radial distortion model, suitable for slight distortion
`RADIAL_K3`	Third-order radial distortion enumeration value	-	Complete radial distortion model, suitable for moderate distortion
`BROWN_CONRADY`	Brown-Conrady distortion enumeration value	-	Complete distortion model including tangential distortion

`CameraModelType`

Camera model type enumeration defining different camera projection models

Enumeration Definitions:

Type	Definition	Default Value	Purpose
`PINHOLE`	Pinhole camera model enumeration value	-	Standard projection camera model, suitable for conventional lenses
`FISHEYE`	Fisheye camera model enumeration value	-	Wide-angle lens model, suitable for large field-of-view cameras
`SPHERICAL`	Spherical camera model enumeration value	-	Spherical projection model, suitable for panoramic cameras
`OMNIDIRECTIONAL`	Omnidirectional camera model enumeration value	-	Full-range projection model, suitable for 360-degree cameras

`CameraIntrinsics`

Camera intrinsic data structure (encapsulated class design, private member variables + public access interface)

Implementation Details:

PIMPL Pattern: Uses std::unique_ptr<Impl> to hide implementation details, providing stable ABI
Memory Alignment: Uses alignas(8) to optimize memory layout, double types prioritized for alignment
Default Construction: Focal length fx/fy defaults to 1.0, principal point cx/cy defaults to 0.0, image size defaults to 0

Internal Data Structure (hidden through PIMPL):

Name	Type	Default Value	Purpose
fx_	`double`	1.0	x-direction focal length parameter
fy_	`double`	1.0	y-direction focal length parameter
cx_	`double`	0.0	x-direction principal point offset coordinate
cy_	`double`	0.0	y-direction principal point offset coordinate
width_	`uint32_t`	0	Image resolution width
height_	`uint32_t`	0	Image resolution height
model_type_	`CameraModelType`	PINHOLE	Camera model type identifier
distortion_type_	`DistortionType`	NO_DISTORTION	Camera distortion type identifier
radial_distortion_	`std::vector<double>`	Empty vector	Radial distortion coefficient array
tangential_distortion_	`std::vector<double>`	Empty vector	Tangential distortion coefficient array

Available Methods:

CameraIntrinsics - Default constructor
GetFx - Get x-direction focal length
GetFy - Get y-direction focal length
GetCx - Get x-direction principal point offset
GetCy - Get y-direction principal point offset
GetWidth - Get image width
GetHeight - Get image height
GetModelType - Get camera model type
GetDistortionType - Get distortion type
GetRadialDistortion - Get radial distortion parameters
GetTangentialDistortion - Get tangential distortion parameters
SetFx - Set x-direction focal length
- fx double: Focal length value
SetFy - Set y-direction focal length
- fy double: Focal length value
SetCx - Set x-direction principal point offset
- cx double: Principal point offset value
SetCy - Set y-direction principal point offset
- cy double: Principal point offset value
SetWidth - Set image width
- width uint32_t: Image width
- Returns void
SetHeight - Set image height
- height uint32_t: Image height
- Returns void
SetImageSize - Batch set image size
- width uint32_t: Image width
- height uint32_t: Image height
- Returns void
SetModelType - Set camera model type
- type CameraModelType: Camera model type
SetDistortionType - Set distortion type
- type DistortionType: Distortion type
GetKMat - Get camera intrinsic matrix (efficient version)
- K Matrix3d &: Output 3x3 intrinsic matrix reference
GetKMat - Get camera intrinsic matrix (convenient version)
- Returns Matrix3d: 3x3 intrinsic matrix
SetKMat - Set camera intrinsic matrix
- K const Matrix3d &: Input 3x3 intrinsic matrix constant reference
SetCameraIntrinsics - Set camera intrinsic data (method 1)
- intrinsics const CameraIntrinsics &: Camera intrinsic structure
SetCameraIntrinsics - Set camera intrinsic data (method 2)
- fx const double: x-direction focal length
- fy const double: y-direction focal length
- cx const double: x-direction principal point offset
- cy const double: y-direction principal point offset
SetCameraIntrinsics - Set camera intrinsic data (method 3)
- fx const double: x-direction focal length
- fy const double: y-direction focal length
- width const uint32_t: Image width
- height const uint32_t: Image height
SetCameraIntrinsics - Set camera intrinsic data (method 4)
- fx const double: x-direction focal length
- fy const double: y-direction focal length
- cx const double: x-direction principal point offset
- cy const double: y-direction principal point offset
- width const uint32_t: Image width
- height const uint32_t: Image height
SetCameraIntrinsics - Set camera intrinsic data (method 5, complete parameters)
- fx const double: x-direction focal length
- fy const double: y-direction focal length
- cx const double: x-direction principal point offset
- cy const double: y-direction principal point offset
- width const uint32_t: Image width
- height const uint32_t: Image height
- radial_distortion const std::vector<double> &: Radial distortion parameters
- tangential_distortion const std::vector<double> &: Tangential distortion parameters (optional, default empty)
- model_type const CameraModelType: Camera model type (default pinhole camera)
SetDistortionParams - Set distortion parameters
- distortion_type DistortionType: Distortion type
- radial_distortion const std::vector<double> &: Radial distortion parameters
- tangential_distortion const std::vector<double> &: Tangential distortion parameters
InitDistortionParams - Initialize distortion parameters to zero
GetFocalLengthPtr - Get focal length parameter pointer (for Ceres optimization)
GetPrincipalPointPtr - Get principal point parameter pointer (for Ceres optimization)
GetDistortionPtr - Get distortion parameter pointer (for Ceres optimization)
CopyToParamArray - Copy parameters to array (for Ceres optimization)
- params double*: Output parameter array
- include_distortion bool: Whether to include distortion parameters (default true)
SetFromParamArray - Set parameters from array (for Ceres optimization)
- params const double*: Input parameter array
- include_distortion bool: Whether to include distortion parameters (default true)

`CameraModel`

Complete camera model definition including intrinsics and metadata information (encapsulated class design, private member variables + public access interface)

Implementation Details:

PIMPL Pattern: Uses std::unique_ptr<Impl> to hide implementation details, providing stable ABI
Memory Alignment: Uses EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro to ensure correct alignment of Eigen types

Internal Data Structure (hidden through PIMPL):

Name	Type	Default Value	Purpose
`intrinsics_`	`CameraIntrinsics`	Default value	Camera intrinsic data structure
`camera_make_`	`std::string`	“”	Camera manufacturer name
`camera_model_`	`std::string`	“”	Camera model identifier
`serial_number_`	`std::string`	“”	Camera serial number

Available Methods:

GetIntrinsics - Get camera intrinsics reference (const version)
- Returns const CameraIntrinsics&: Intrinsics constant reference
GetIntrinsics - Get camera intrinsics reference (non-const version)
- Returns CameraIntrinsics&: Intrinsics reference
GetCameraMake - Get camera manufacturer
- Returns const std::string&: Manufacturer name
GetCameraModel - Get camera model name
- Returns const std::string&: Camera model name (e.g., “EOS 5D Mark IV”)
GetSerialNumber - Get serial number
- Returns const std::string&: Serial number
SetCameraMake - Set camera manufacturer
- make const std::string&: Manufacturer name
SetCameraModelName - Set camera model name
- model const std::string&: Camera model name
SetSerialNumber - Set serial number
- serial const std::string&: Serial number
PixelToNormalized - Pixel coordinate to normalized coordinate (single point conversion)
- pixel_coord const Vector2d &: Pixel coordinate
- Returns Vector2d: Normalized coordinate
NormalizedToPixel - Normalized coordinate to pixel coordinate (single point conversion)
- normalized_coord const Vector2d &: Normalized coordinate
- Returns Vector2d: Pixel coordinate
PixelToNormalizedBatch - Batch pixel coordinate to normalized coordinate (vectorized)
- pixel_coords const Eigen::Ref<const Eigen::Matrix<double, 2, Eigen::Dynamic>>&: 2×N pixel coordinate matrix
- Returns Eigen::Matrix<double, 2, Eigen::Dynamic>: 2×N normalized coordinate matrix
- Note: SIMD-friendly batch operation, better performance than loop calling single point conversion
NormalizedToPixelBatch - Batch normalized coordinate to pixel coordinate (vectorized)
- normalized_coords const Eigen::Ref<const Eigen::Matrix<double, 2, Eigen::Dynamic>>&: 2×N normalized coordinate matrix
- Returns Eigen::Matrix<double, 2, Eigen::Dynamic>: 2×N pixel coordinate matrix
- Note: SIMD-friendly batch operation, better performance than loop calling single point conversion
SetKMat - Set camera intrinsic matrix
- K const Matrix3d &: Input 3x3 intrinsic matrix
GetKMat - Get camera intrinsic matrix (efficient version)
- K Matrix3d &: Output 3x3 intrinsic matrix reference
GetKMat - Get camera intrinsic matrix (convenient version)
- Returns Matrix3d: 3x3 intrinsic matrix
SetDistortionParams - Set distortion type and parameters
- distortion_type const DistortionType &: Distortion type
- radial_distortion const std::vector<double> &: Radial distortion parameters
- tangential_distortion const std::vector<double> &: Tangential distortion parameters
SetModelType - Set camera model type
- model_type const CameraModelType &: Camera model type
SetCameraInfo - Set camera metadata information
- camera_make const std::string &: Camera manufacturer
- camera_model const std::string &: Camera model
- serial_number const std::string &: Serial number
Other SetCameraIntrinsics methods - Multiple overloaded methods same as CameraIntrinsics class
GetFocalLengthPtr - Get focal length parameter pointer (for Ceres optimization)
GetPrincipalPointPtr - Get principal point parameter pointer (for Ceres optimization)
GetDistortionPtr - Get distortion parameter pointer (for Ceres optimization)
CopyToParamArray - Copy parameters to array (for Ceres optimization)
- params double*: Output parameter array
- include_distortion bool: Whether to include distortion parameters (default true)
SetFromParamArray - Set parameters from array (for Ceres optimization)
- params const double*: Input parameter array
- include_distortion bool: Whether to include distortion parameters (default true)

`CameraModels`

Intelligent camera model container class supporting single and multi-camera configurations, inherits from std::vector<CameraModel>

Available Methods:

operator[] - Intelligent index access to camera model (non-const version)
- view_id ViewId: View identifier
- Returns CameraModel*: Camera model pointer, returns nullptr on access failure
operator[] - Intelligent index access to camera model (const version)
- view_id ViewId: View identifier
- Returns const CameraModel*: Camera model constant pointer, returns nullptr on access failure
at - Intelligent index access to camera model (non-const version, with bounds checking)
- view_id ViewId: View identifier
- Returns CameraModel&: Camera model reference
- Throws exception: std::out_of_range (when access is invalid)
at - Intelligent index access to camera model (const version, with bounds checking)
- view_id ViewId: View identifier
- Returns const CameraModel&: Camera model constant reference
- Throws exception: std::out_of_range (when access is invalid)
All standard container methods inherited from std::vector<CameraModel> (size, empty, push_back, clear, etc.)

Camera Model Related Type Definitions

Type Definitions:

Type	Definition	Default Value	Purpose
`CameraModelPtr`	`std::shared_ptr<CameraModel>`	nullptr	Camera model smart pointer type
`CameraModelsPtr`	`std::shared_ptr<CameraModels>`	nullptr	Camera model collection smart pointer type
`KMats`	`std::vector<Matrix3d, Eigen::aligned_allocator<Matrix3d>>`	Empty vector	Intrinsic matrix sequence container using aligned allocator
`KMatsPtr`	`std::shared_ptr<KMats>`	nullptr	Intrinsic matrix sequence smart pointer

Image Management (types/image.hpp)

Image Path Type Definitions

Type Definitions:

Type	Definition	Default Value	Purpose
`ImagePaths`	`std::vector<std::pair<std::string, bool>>`	Empty vector	Type definition for storing image paths and their validity status
`ImagePathsPtr`	`std::shared_ptr<ImagePaths>`	nullptr	Smart pointer type for image path collection

Features (types/features.hpp)

The feature system adopts SIMD-optimized SOA (Structure of Arrays) design, providing high-performance feature data management.

Core Features and Usage Patterns

SIMD-Optimized SOA Design Advantages:

SOA Memory Layout: Data stored grouped by type, improving cache locality and SIMD vectorization efficiency
AVX2/AVX-512 Support: Batch operations fully vectorized, significantly improving performance
Natural Alignment Optimization: Removes excessive 64-byte alignment, reducing 90%+ memory usage
Batch-First API: Provides efficient batch operation interfaces (SetSizesBlock, SetAnglesBlock, etc.)
Zero-Copy Compatibility: Zero-copy compatible with cv::Mat and protobuf, 8-9x faster conversion
Compact Layout: Single continuous memory allocation, reducing memory fragmentation

Typical Usage Examples

FeaturePoints Batch Operations (High Performance)

using namespace PoSDK::types;

// Create feature point collection (recommended to reserve capacity)
FeaturePoints features(1000);  // Reserve 1000 feature points

// Batch add features (efficient)
Eigen::Matrix<double, 2, Eigen::Dynamic> coords_block(2, 100);
std::vector<float> sizes_block(100, 5.0f);
std::vector<float> angles_block(100, 0.0f);
// ... Fill coords_block, sizes_block, angles_block ...
features.AddFeaturesBlock(coords_block, sizes_block.data(), angles_block.data());

// Access individual feature point
Feature coord = features.GetCoord(0);
float size = features.GetSize(0);
float angle = features.GetAngle(0);

// Batch set attributes (SIMD optimized)
features.SetSizesBlock(0, 100, sizes_block.data());
features.SetAnglesBlock(0, 100, angles_block.data());

// Batch statistical operations (SIMD optimized)
features.IncrementTotalCountsBlock(0, 100);
features.IncrementOutlierCountsBlock(0, 50);

// Zero counters (SIMD optimized)
features.ZeroCounters();

// Get valid feature count (SIMD optimized)
Size valid_count = features.GetNumValid();

// Iterator access
for (auto&& feat_proxy : features) {
    if (feat_proxy.IsUsed()) {
        Feature coord = feat_proxy.GetCoord();
        // Process feature
    }
}

Descriptor Management (SOA Format)

// Create SOA descriptor container (high performance)
DescriptorsSOA descs_soa(1000, 128);  // 1000 features, 128-dimensional SIFT descriptor

// Set single descriptor
float descriptor_data[128];
// ... Fill descriptor_data ...
descs_soa.SetDescriptor(0, descriptor_data);

// Direct access to descriptor data (zero-copy)
float* desc_ptr = descs_soa[0];  // Pointer to the 0th descriptor

// Batch copy (SIMD optimized)
float* all_descs = descs_soa.data();  // Raw data pointer
size_t total_size = descs_soa.total_size();  // Total number of elements

// Convert from old AOS format (automatic)
Descs old_format_descs;  // std::vector<std::vector<float>>
descs_soa.FromDescs(old_format_descs);

// Convert back to AOS format (compatibility)
Descs converted_descs;
descs_soa.ToDescs(converted_descs);

Image Feature Information Management

// Create image feature information
ImageFeatureInfo image_features("image1.jpg", true);

// Reserve capacity (recommended)
image_features.ReserveFeatures(1000);

// Add single feature point
image_features.AddFeature(100.0f, 200.0f, 5.0f, 45.0f);

// Batch add features (efficient)
Eigen::Matrix<double, 2, Eigen::Dynamic> coords_block(2, 100);
std::vector<float> sizes_block(100, 5.0f);
std::vector<float> angles_block(100, 0.0f);
// ... Fill data ...
image_features.AddFeaturesBlock(coords_block, sizes_block.data(), angles_block.data());

// Access feature point collection (direct access to underlying FeaturePoints)
FeaturePoints& features = image_features.GetFeaturePoints();
Size num_features = features.size();

// Access single feature through proxy (compatibility method)
auto feat_proxy = image_features.GetFeature(0);
Feature coord = feat_proxy.GetCoord();
float size = feat_proxy.GetSize();

// Zero feature counters (SIMD optimized)
image_features.ZeroFeatureCounters();

// Get valid feature count
Size valid_features = image_features.GetNumValidFeatures();

// Clear unused features
image_features.ClearUnusedFeatures();

// Descriptor management
auto descs_soa = std::make_shared<DescriptorsSOA>(1000, 128);
image_features.SetDescriptorsSOA(descs_soa);  // Set SOA format descriptor

if (image_features.HasDescriptorsSOA()) {
    auto& desc_ref = image_features.GetDescriptorsSOAPtr();
    // Use descriptor...
}

// Check descriptor reference count (memory debugging)
long soa_ref_count = image_features.GetDescriptorsSOARefCount();

Feature Collection Management

// Create feature information collection
FeaturesInfo features_info;

// Add image features
features_info.AddImageFeatures("image1.jpg", true);
features_info.AddImageFeatures("image2.jpg", true);

// Intelligent access to image features
ImageFeatureInfo* img_feat = features_info[0];  // Returns pointer, need to check nullptr
if (img_feat) {
    img_feat->AddFeature(FeaturePoint(10.0f, 20.0f));
    std::string path = img_feat->GetImagePath();
}

// Safe access to image features
const ImageFeatureInfo* safe_img_feat = features_info.GetImageFeaturePtr(1);
if (safe_img_feat) {
    Size num_features = safe_img_feat->GetNumFeatures();
}

// Management operations
Size valid_images = features_info.GetNumValidImages();
features_info.ClearUnusedImages();
features_info.ClearAllUnusedFeatures();

Fundamental Feature Types

Type Definitions:

Type	Definition	Default Value	Purpose
`Feature`	`Eigen::Matrix<double, 2, 1>`	Zero vector	Basic 2D feature point, contains only position information
`Descriptor`	`std::vector<float>`	Empty vector	Legacy AOS format descriptor (backward compatible)
`Descs`	`std::vector<Descriptor>`	Empty vector	Legacy AOS format descriptor collection (backward compatible)
`DescriptorsSOA`	SOA format descriptor container class	-	High-performance SOA format descriptor, SIMD optimized
`DescsSOA`	`DescriptorsSOA`	-	Type alias for DescriptorsSOA
`DescsSOAPtr`	`Ptr<DescriptorsSOA>`	nullptr	Smart pointer for DescriptorsSOA
`FeaturePoints`	SOA format feature point container class	-	High-performance SOA format feature point collection, SIMD optimized
`FeaturePointsPtr`	`Ptr<FeaturePoints>`	nullptr	Smart pointer for FeaturePoints

`DescriptorsSOA` (Recommended)

SIMD-optimized descriptor container using SOA (Structure of Arrays) format, providing zero-copy compatibility and 8-9x faster CV↔PoSDK conversion

Key Features:

Single Memory Allocation: All descriptors in one contiguous memory block (vs 10K scattered allocations)
SIMD-Friendly: Supports AVX2/AVX-512 batch operations
Zero-Copy Compatibility: Seamless integration with cv::Mat and protobuf
Compact Layout: num_features × descriptor_dim × sizeof(float)

Memory Layout:

[desc0[0], desc0[1], ..., desc0[dim-1], desc1[0], desc1[1], ..., desc1[dim-1], ...]

Available Methods:

DescriptorsSOA - Default constructor
DescriptorsSOA - Parameterized constructor
- num_features size_t: Number of features
- descriptor_dim size_t: Descriptor dimension
resize - Resize
- num_features size_t: Number of features
- descriptor_dim size_t: Descriptor dimension
- Returns void
reserve - Reserve capacity
- num_features size_t: Number of features
- descriptor_dim size_t: Descriptor dimension
- Returns void
clear - Clear data
- Returns void
size - Get number of features
- Returns size_t: Number of features
dim - Get descriptor dimension
- Returns size_t: Descriptor dimension
total_size - Get total data size
- Returns size_t: Total data size (num_features × descriptor_dim)
empty - Check if empty
- Returns bool: Whether empty
data - Get raw data pointer (batch operations)
- Returns float* / const float*: Raw data pointer
operator[] - Get descriptor pointer
- feature_idx size_t: Feature index
- Returns float* / const float*: Pointer to descriptor_dim floats
SetDescriptor - Set single descriptor (SIMD optimized)
- feature_idx size_t: Feature index
- descriptor_data const float*: Descriptor data pointer
- Returns void
GetDescriptor - Get single descriptor (SIMD optimized)
- feature_idx size_t: Feature index
- descriptor_out float*: Output buffer
- Returns void
FromDescs - Convert from legacy AOS format
- descs const Descs&: Legacy descriptor vector
- Returns void
ToDescs - Convert to legacy AOS format
- descs Descs&: Output legacy descriptor vector
- Returns void

`FeaturePoints` (Recommended)

SIMD-optimized SOA feature point container with natural alignment, providing batch-first API

Key Features:

SOA Memory Layout: Coordinates, sizes, and angles stored separately, SIMD-friendly
Natural Alignment: Reduces 90%+ memory usage, improves cache efficiency
Batch Operations: Fully vectorized batch set/update operations (AVX2/AVX-512)
Iterator Support: Provides STL-style iterators and range-based for loops

Available Methods:

FeaturePoints - Default constructor
FeaturePoints - Constructor with reserved capacity
- reserve_size Size: Reserved size
reserve - Reserve capacity
- capacity Size: Reserved size
- Returns void
resize - Resize
- new_size Size: New size
- Returns void
clear - Clear data
- Returns void
size - Get number of features
- Returns Size: Number of features
empty - Check if empty
- Returns bool: Whether empty
GetSize - Get single feature size
- idx Size: Feature index
- Returns float& / const float&: Feature size reference
GetAngle - Get single feature angle
- idx Size: Feature index
- Returns float& / const float&: Feature angle reference
IsUsed - Get single feature usage status
- idx Size: Feature index
- Returns uint8_t& / const uint8_t&: Usage status reference
GetCoord - Get single feature coordinate
- idx Size: Feature index
- Returns Feature: Feature coordinate
SetCoord - Set single feature coordinate
- idx Size: Feature index
- coord const Feature&: Coordinate
- Returns void
GetCoordsRef - Get coordinate matrix reference (batch operations)
- Returns Eigen::Matrix<double, 2, Eigen::Dynamic>&
GetSizesRef - Get size vector reference (batch operations)
- Returns std::vector<float>&
GetAnglesRef - Get angle vector reference (batch operations)
- Returns std::vector<float>&
GetIsUsedRef - Get usage flag vector reference (batch operations)
- Returns std::vector<uint8_t>&
GetTotalCountsRef - Get total count vector reference (batch operations)
- Returns std::vector<IndexT>&
GetOutlierCountsRef - Get outlier count vector reference (batch operations)
- Returns std::vector<IndexT>&
SetCoordsBlock - Batch set coordinates (SIMD optimized)
- start Size: Start index
- count Size: Count
- coords_block const Eigen::Ref<const Eigen::Matrix<double, 2, Eigen::Dynamic>>&: Coordinate block
- Returns void
SetSizesBlock - Batch set sizes (SIMD optimized)
- start Size: Start index
- count Size: Count
- sizes_block const float*: Size data pointer
- Returns void
SetAnglesBlock - Batch set angles (SIMD optimized)
- start Size: Start index
- count Size: Count
- angles_block const float*: Angle data pointer
- Returns void
SetIsUsedBlock - Batch set usage flags (SIMD optimized)
- start Size: Start index
- count Size: Count
- flags const uint8_t*: Flag data pointer
- Returns void
IncrementTotalCountsBlock - Batch increment total counts (SIMD optimized)
- start Size: Start index
- count Size: Count
- Returns void
IncrementOutlierCountsBlock - Batch increment outlier counts (SIMD optimized)
- start Size: Start index
- count Size: Count
- Returns void
GetNumValid - Get valid feature count (SIMD optimized)
- Returns Size: Valid feature count
GetOutlierRatiosBlock - Batch get outlier ratios (SIMD optimized)
- start Size: Start index
- count Size: Count
- ratios_out double*: Output buffer
- Returns void
AddFeature - Add single feature (method 1)
- coord const Feature&: Coordinate
- size float: Size (default 0.0f)
- angle float: Angle (default 0.0f)
- Returns void
AddFeature - Add single feature (method 2)
- x float: x coordinate
- y float: y coordinate
- size float: Size (default 0.0f)
- angle float: Angle (default 0.0f)
- Returns void
AddFeaturesBlock - Batch add features (SIMD optimized)
- coords_block const Eigen::Ref<const Eigen::Matrix<double, 2, Eigen::Dynamic>>&: Coordinate block
- sizes_block const float*: Size data pointer (optional)
- angles_block const float*: Angle data pointer (optional)
- Returns void
RemoveUnused - Remove unused features
- Returns void
ZeroCounters - Batch zero counters (SIMD optimized)
- Returns void
operator[] - Array-style access (returns proxy object)
- index Size: Feature index
- Returns FeaturePointProxy: Proxy object
begin, end - STL-style iterators
- Returns SimpleIterator: Iterator object

Tip

Performance Tips | 性能建议

Prioritize Batch Operations: Use batch APIs like AddFeaturesBlock, SetSizesBlock, etc., to fully utilize SIMD acceleration
Reserve Capacity: Use reserve() to avoid multiple memory reallocations
Direct Access: Use reference interfaces like GetCoordsRef() for batch processing
SOA Descriptors: Prefer DescriptorsSOA over legacy Descs for 8-9x speedup

`FeaturePoint` (Legacy, Retained for Compatibility)

Legacy feature point class (replaced by FeaturePoints, retained for compatibility)

Warning

Deprecated | 已弃用

The FeaturePoint class has been replaced by the high-performance FeaturePoints SOA container. New code should directly use FeaturePoints and its proxy object FeaturePointProxy.

The legacy FeaturePoint is retained only for backward compatibility and is not recommended for use in new code.

`ImageFeatureInfo`

Single image feature information encapsulation class with SIMD-optimized SOA design, including optional descriptor management

Private Member Variables:

Name	Type	Default Value	Purpose
`image_path_`	`std::string`	“”	Image file path string
`features_`	`FeaturePoints`	Default value	Feature point collection (SOA format, SIMD optimized)
`is_used_`	`bool`	true	Usage status of this image feature information
`descriptors_ptr_`	`Ptr<Descs>`	nullptr	Legacy AOS descriptor pointer (backward compatible, optional)
`descriptors_soa_ptr_`	`Ptr<DescriptorsSOA>`	nullptr	SOA descriptor pointer (high performance, optional, recommended)

Available Methods:

ImageFeatureInfo - Default constructor
ImageFeatureInfo - Parameterized constructor
- path const std::string &: Image file path
- used bool: Usage flag (default true)
GetImagePath - Get image path
- Returns const std::string&: Image path reference
SetImagePath - Set image path
- path const std::string&: Image path
IsUsed - Get usage status
SetUsed - Set usage status
- used bool: Whether used
GetFeaturePoints - Get feature point collection (non-const version)
- Returns FeaturePoints&: Feature point collection reference
GetFeaturePoints - Get feature point collection (const version)
- Returns const FeaturePoints&: Feature point collection const reference
GetNumFeatures - Get feature point count
GetNumValidFeatures - Get valid feature point count (SIMD optimized)
AddFeature - Add single feature (method 1)
- coord const Feature&: Coordinate
- size float: Size (default 0.0f)
- angle float: Angle (default 0.0f)
AddFeature - Add single feature (method 2)
- x float: x coordinate
- y float: y coordinate
- size float: Size (default 0.0f)
- angle float: Angle (default 0.0f)
AddFeaturesBlock - Batch add features (SIMD optimized)
- coords_block const Eigen::Ref<const Eigen::Matrix<double, 2, Eigen::Dynamic>>&: Coordinate block
- sizes_block const float*: Size data pointer (optional)
- angles_block const float*: Angle data pointer (optional)
ClearUnusedFeatures - Clear unused feature points
ClearAllFeatures - Clear all feature points
ReserveFeatures - Reserve feature point capacity
- capacity Size: Reserved capacity
ZeroFeatureCounters - Zero feature counters (SIMD optimized)
empty - Check if empty
size - Get feature point count
begin, end - Iterator access
HasDescriptors - Check if descriptors are stored (AOS or SOA)
HasDescriptorsSOA - Check if SOA descriptors are stored
GetDescriptorsPtr - Get legacy AOS descriptor pointer (const version)
- Returns const Ptr<Descs>&
GetDescriptorsPtr - Get legacy AOS descriptor pointer (non-const version)
- Returns Ptr<Descs>&
SetDescriptors - Set legacy AOS descriptors
- descs_ptr const Ptr<Descs>&: Descriptor pointer
GetDescriptorsSOAPtr - Get SOA descriptor pointer (const version) (recommended)
- Returns const Ptr<DescriptorsSOA>&
GetDescriptorsSOAPtr - Get SOA descriptor pointer (non-const version) (recommended)
- Returns Ptr<DescriptorsSOA>&
SetDescriptorsSOA - Set SOA descriptors (recommended)
- descs_soa_ptr const Ptr<DescriptorsSOA>&: SOA descriptor pointer
ClearDescriptors - Clear descriptors and release memory
GetDescriptorsRefCount - Get AOS descriptor reference count (for debugging)
GetDescriptorsSOARefCount - Get SOA descriptor reference count (for debugging)
GetFeature - Get feature proxy object (compatibility method)
- index Size: Feature index
- Returns FeatureProxy: Feature proxy object

`FeaturesInfo`

Feature information collection for all images, enhanced container class inheriting from std::vector<ImageFeatureInfo>

Available Methods:

operator[] - Array-style access (non-const version)
- index Size: Image index
- Returns ImageFeatureInfo*: Image feature information pointer, returns nullptr if out of bounds
operator[] - Array-style access (const version)
- index Size: Image index
- Returns const ImageFeatureInfo*: Image feature information const pointer, returns nullptr if out of bounds
GetImageFeaturePtr - Safely get image feature information pointer (non-const version)
- index Size: Image index
- Returns ImageFeatureInfo*: Image feature information pointer, returns nullptr if out of bounds
GetImageFeaturePtr - Safely get image feature information pointer (const version)
- index Size: Image index
- Returns const ImageFeatureInfo*: Image feature information const pointer, returns nullptr if out of bounds
AddImageFeatures - Add image feature information
- image_path const std::string &: Image path
- is_used bool: Usage flag (default true)
GetNumValidImages - Get valid image count
ClearUnusedImages - Clear unused images
ClearAllUnusedFeatures - Clear all unused feature points
Print - Print feature information details
- print_unused bool: Whether to print unused features (default false)

Matching (types/matches.hpp)

`IdMatch`

Feature point matching structure

Member Variables:

Name	Type	Default Value	Purpose
`i`	`IndexT`	0	Index identifier of the first feature
`j`	`IndexT`	0	Index identifier of the second feature
`is_inlier`	`bool`	false	RANSAC inlier flag, indicates matching quality

Match Collection Type Definitions

Type Definitions:

Type	Definition	Default Value	Purpose
`IdMatches`	`std::vector<IdMatch>`	Empty vector	Feature matching collection, stores all matches between an image pair
`ViewPair`	`std::pair<IndexT,` `IndexT>`	(0,0)	View index pair, identifies a combination of two views
`Matches`	`std::map<ViewPair,` `IdMatches>`	Empty map	Match relationship mapping between all view pairs
`MatchesPtr`	`std::shared_ptr<Matches>`	nullptr	Smart pointer type for match collection

Bearing Vector Type Definitions

Type Definitions:

Type	Definition	Default Value	Purpose
`BearingVector`	`Vector3d`	Zero vector	Unit observation vector type, from camera center to 3D point
`BearingVectors`	`Eigen::Matrix<double,3,Eigen::Dynamic>`	Zero matrix	3×N observation vector matrix, stores multiple observation vectors
`BearingPairs`	`std::vector<Eigen::Matrix<double,6,1>>`	Empty vector	Matched bearing vector pairs for relative pose estimation

Bearing Vector Utility Functions

Available Functions:

PixelToBearingVector - Convert pixel coordinates to unit observation vector
- pixel_coord const Vector2d &: Pixel coordinates
- camera_model const CameraModel &: Camera model
- Returns BearingVector: Unit observation vector
PixelToBearingVector - Convert pixel coordinates to unit observation vector (overloaded version)
- pixel_coord const Vector2d &: Pixel coordinates
- fx double: x-direction focal length
- fy double: y-direction focal length
- cx double: x-direction principal point offset
- cy double: y-direction principal point offset
- Returns BearingVector: Unit observation vector
MatchesToBearingPairs - Convert matches to bearing vector pairs
- matches const IdMatches &: Feature matches
- features_info const FeaturesInfo &: Feature information for all views
- camera_models const CameraModels &: Camera models for all views
- view_pair const ViewPair &: View pair index
- bearing_pairs BearingPairs &: Output bearing vector pairs
- Returns bool: Whether successful
MatchesToBearingPairsInliersOnly - Convert inlier matches to bearing vector pairs
- matches const IdMatches &: Feature matches
- features_info const FeaturesInfo &: Feature information for all views
- camera_models const CameraModels &: Camera models for all views
- view_pair const ViewPair &: View pair index
- bearing_pairs BearingPairs &: Output bearing vector pairs (inliers only)
- Returns bool: Whether successful

Tracks and Observations (types/tracks.hpp)

The track system uses an encapsulation class design, providing better data security and access control.

Core Features and Usage Patterns

Encapsulation Design Advantages:

Private Member Variables: Prevent accidental modification, improve data security
Public Access Interfaces: Provide unified data access and modification methods
Memory Alignment Optimization: Use Eigen aligned_allocator for improved performance, includes EIGEN_MAKE_ALIGNED_OPERATOR_NEW macro
Container-Style Interface: Support STL container usage patterns

Typical Usage Examples

Basic Observation Information Creation and Operations

using namespace PoSDK::types;

// Create observation information
ObsInfo obs1;  // Default construction
ObsInfo obs2(0, 1, Vector2d(100.0, 200.0));  // View ID, feature ID, coordinates

// Set and get properties
obs1.SetViewId(1);
obs1.SetFeatureId(5);  // Set feature index in FeaturesInfo[view_id]
obs1.SetObsId(123);
obs1.SetCoord(Vector2d(150.0, 250.0));
obs1.SetUsed(true);

// Get properties
ViewId view_id = obs1.GetViewId();
IndexT feature_id = obs1.GetFeatureId();  // Get feature ID
IndexT obs_id = obs1.GetObsId();
const Vector2d& coord = obs1.GetCoord();
bool is_used = obs1.IsUsed();

// Get homogeneous coordinates
Vector3d homo_coord = obs1.GetHomoCoord();

Track Information Management

// Create track information
TrackInfo track_info;

// Add observations
track_info.AddObservation(0, 1, Vector2d(100.0, 200.0));  // View ID, feature ID, coordinates
track_info.AddObservation(obs1);  // Directly add observation object

// Access observations
Size obs_count = track_info.GetObservationCount();
Size valid_count = track_info.GetValidObservationCount();

// Array-style access (returns pointer)
const ObsInfo* obs_ptr = track_info[0];
if (obs_ptr) {
    Vector2d coord = obs_ptr->GetCoord();
}

// Safe access (reference access, throws exception if out of bounds)
try {
    const ObsInfo& obs_ref = track_info.GetObservation(1);
    ViewId view_id = obs_ref.GetViewId();
} catch (const std::out_of_range& e) {
    // Handle out-of-bounds access
}

// Get track data
const Track& track = track_info.GetTrack();
Track& mutable_track = track_info.GetTrack();

// Set track usage status
track_info.SetUsed(true);
bool track_used = track_info.IsUsed();

// Set observation status
track_info.SetObservationUsed(0, false);
track_info.SetObservationFeatureId(0, 10);

Track Collection Management

// Create track collection
Tracks tracks;

// Add tracks
std::vector<ObsInfo> observations = {obs1, obs2};
tracks.AddTrack(observations);
tracks.AddTrack(track_info);

// Direct addition (compatibility method)
tracks.push_back(track_info);
tracks.emplace_back(observations, true);

// Access tracks
Size track_count = tracks.size();
Size valid_track_count = tracks.GetValidTrackCount();

// Array-style access (returns pointer)
const TrackInfo* track_ptr = tracks[0];
if (track_ptr) {
    Size obs_count = track_ptr->GetObservationCount();
}

// Safe access (reference access, throws exception if out of bounds)
try {
    const TrackInfo& track_ref = tracks.GetTrack(1);
    bool is_used = track_ref.IsUsed();
} catch (const std::out_of_range& e) {
    // Handle out-of-bounds access
}

// Quick observation access: Tracks[point ID, view ID]
const ObsInfo* obs_ptr = tracks(1, 0);  // Point ID=1, View ID=0
if (obs_ptr) {
    Vector2d coord = obs_ptr->GetCoord();
}

// Iterator access
for (const auto& track_info : tracks) {
    if (track_info.IsUsed()) {
        for (const auto& obs : track_info.GetTrack()) {
            if (obs.IsUsed()) {
                Vector2d coord = obs.GetCoord();
                // Process observation
            }
        }
    }
}

// Normalization processing
CameraModels camera_models;
// ... Set camera models ...
bool normalized = tracks.NormalizeTracks(camera_models);
bool is_normalized = tracks.IsNormalized();
tracks.SetNormalized(true);

`ObsInfo`

Single observation information encapsulation class for a 3D point, providing private members and public access interfaces

Private Member Variables:

Name	Type	Default Value	Purpose
`coord_`	`Vector2d`	Zero vector	Current 2D coordinates (may be original or reprojected)
`original_coord_`	`std::vector<double>`	Empty vector	Original image coordinates (empty if not stored)
`view_id_`	`ViewId`	0	Image ID (consistent with index in ImagePaths)
`feature_id_`	`IndexT`	0	Feature point ID index in FeaturesInfo[view_id]
`obs_id_`	`IndexT`	0	Observation ID
`is_used_`	`bool`	true	Whether the current observation is used
`color_rgb_`	`std::array<uint8_t, 3>`	{0,0,0}	RGB color values (0-255)

Available Methods:

ObsInfo - Default constructor
ObsInfo - Parameterized constructor
- vid ViewId: View ID
- fid IndexT: Feature ID
- c const Vector2d &: Observation coordinates
GetCoord - Get observation coordinates
- Returns const Vector2d&: Observation coordinate reference
SetCoord - Set observation coordinates
- coord const Vector2d&: Observation coordinates
- Returns void
GetViewId - Get view ID
- Returns ViewId: View ID
SetViewId - Set view ID
- view_id ViewId: View ID
- Returns void
GetFeatureId - Get feature ID
- Returns IndexT: Feature ID (index in FeaturesInfo[view_id])
SetFeatureId - Set feature ID
- feature_id IndexT: Feature ID (index in FeaturesInfo[view_id])
- Returns void
GetObsId - Get observation ID
- Returns IndexT: Observation ID
SetObsId - Set observation ID
- obs_id IndexT: Observation ID
- Returns void
IsUsed - Get usage status
- Returns bool: Usage status flag
SetUsed - Set observation usage status
- used bool: Whether used flag
- Returns void
GetColorRGB - Get RGB color
- Returns const std::array<uint8_t, 3>&: RGB color array reference
SetColorRGB - Set RGB color (method 1)
- r uint8_t: Red component (0-255)
- g uint8_t: Green component (0-255)
- b uint8_t: Blue component (0-255)
- Returns void
SetColorRGB - Set RGB color (method 2)
- rgb const std::array<uint8_t, 3>&: RGB color array
- Returns void
HasColor - Check if color information exists
- Returns bool: Whether there are non-zero color values
HasOriginalCoord - Check if original coordinates are stored
- Returns bool: Whether original coordinates are stored
StoreOriginalCoord - Store current coordinates as original coordinates
- Returns void
ResetToOriginalCoord - Reset current coordinates to original coordinates
- Returns void
GetOriginalCoord - Get original coordinates
- Returns Vector2d: Original coordinates (returns current coordinates if not stored)
GetReprojectionError - Calculate reprojection error
- Returns double: Euclidean distance between current and original coordinates (returns -1.0 if no original data)
GetCoord - Get observation coordinates (compatibility version)
- coord_out Vector2d &: Output coordinate reference
- Returns bool: Whether successfully retrieved
GetHomoCoord - Get homogeneous coordinates
- Returns Vector3d: Homogeneous coordinates

`Track`

3D point observation information collection, type alias: std::vector<ObsInfo, Eigen::aligned_allocator<ObsInfo>>

`TrackInfo`

Track information encapsulation class providing private members and public access interfaces

Private Member Variables:

Name	Type	Default Value	Purpose
`track_`	`Track`	Default value	Track observation data
`is_used_`	`bool`	true	Whether this track is used

Available Methods:

TrackInfo - Default constructor
TrackInfo - Parameterized constructor (method 1)
- t const Track &: Track data
- used bool: Usage flag (default true)
TrackInfo - Parameterized constructor (method 2)
- observations const std::vector<ObsInfo> &: Observation array
- used bool: Usage flag (default true)
GetTrack - Get track data (non-const version)
- Returns Track&: Track data reference
GetTrack - Get track data (const version)
- Returns const Track&: Track data const reference
IsUsed - Get usage status
- Returns bool: Usage status flag
SetUsed - Set track usage status
- used bool: Whether to use this track
- Returns void
operator[] - Array-style access (non-const version)
- index Size: Observation index
- Returns ObsInfo*: Observation pointer, returns nullptr if out of bounds
operator[] - Array-style access (const version)
- index Size: Observation index
- Returns const ObsInfo*: Observation const pointer, returns nullptr if out of bounds
GetObservation - Get observation information (non-const version)
- index IndexT: Observation index
- Returns ObsInfo&: Observation reference (throws exception if out of bounds)
GetObservation - Get observation information (const version)
- index IndexT: Observation index
- Returns const ObsInfo&: Observation const reference (throws exception if out of bounds)
AddObservation - Add observation (method 1)
- view_id ViewId: View ID
- feature_id IndexT: Feature ID (index in FeaturesInfo[view_id])
- coord const Vector2d &: Observation coordinates
- Returns void
AddObservation - Add observation (method 2)
- obs const ObsInfo &: Observation information
- Returns void
GetObservationCount - Get observation count
- Returns Size: Observation count
GetValidObservationCount - Get valid observation count
- Returns Size: Valid observation count
GetObservationCoord - Get coordinates of specified observation
- index IndexT: Observation index
- coord_out Vector2d &: Output coordinate reference
- Returns bool: Whether successfully retrieved
SetObservationUsed - Set usage status of specified observation
- index IndexT: Observation index
- used bool: Whether to use this observation
- Returns void
SetObservationFeatureId - Set feature ID of specified observation
- index IndexT: Observation index
- feature_id IndexT: Feature ID (index in FeaturesInfo[view_id])
- Returns void
ClearObservations - Clear observation data
- Returns void
ReserveObservations - Reserve observation capacity
- capacity Size: Reserved capacity
- Returns void
size - Get observation count
- Returns Size: Observation count
empty - Check if empty
- Returns bool: Whether empty
begin, end - Iterator access
- Returns iterator object

`Tracks`

Track collection encapsulation class providing complete track management interface

Private Member Variables:

Name	Type	Default Value	Purpose
`tracks_`	`std::vector<TrackInfo, Eigen::aligned_allocator<TrackInfo>>`	Empty vector	Track information vector
`is_normalized_`	`bool`	false	Normalization status flag

Available Methods:

IsNormalized - Get normalization status
- Returns bool: Normalization status flag
SetNormalized - Set normalization status
- normalized bool: Normalization flag
- Returns void
size - Get track count
- Returns Size: Track count
empty - Check if empty
- Returns bool: Whether empty
clear - Clear all tracks
- Returns void
reserve - Reserve capacity
- n Size: Reserved size
- Returns void
operator[] - Array-style access (non-const version)
- index Size: Track index
- Returns TrackInfo*: Track pointer, returns nullptr if out of bounds
operator[] - Array-style access (const version)
- index Size: Track index
- Returns const TrackInfo*: Track const pointer, returns nullptr if out of bounds
GetTrack - Get track (non-const version)
- index Size: Track index
- Returns TrackInfo&: Track reference (throws exception if out of bounds)
GetTrack - Get track (const version)
- index Size: Track index
- Returns const TrackInfo&: Track const reference (throws exception if out of bounds)
operator() - Quick observation access (non-const version)
- pts_id PtsId: Point ID
- view_id ViewId: View ID
- Returns ObsInfo*: Observation pointer, returns nullptr if not found
operator() - Quick observation access (const version)
- pts_id PtsId: Point ID
- view_id ViewId: View ID
- Returns const ObsInfo*: Observation const pointer, returns nullptr if not found
GetObservation - Get observation (non-const version)
- pts_id PtsId: Point ID
- view_id ViewId: View ID
- Returns ObsInfo*: Observation pointer, returns nullptr if not found
GetObservation - Get observation (const version)
- pts_id PtsId: Point ID
- view_id ViewId: View ID
- Returns const ObsInfo*: Observation const pointer, returns nullptr if not found
begin, end - Iterator access
- Returns iterator object
cbegin, cend - Const iterator access
- Returns const iterator object
AddTrack - Add new track (method 1)
- observations const std::vector<ObsInfo> &: Observation information array
- Returns void
AddTrack - Add new track (method 2)
- track_info const TrackInfo &: Track information
- Returns void
AddObservation - Add observation to specified track
- track_id PtsId: Track ID (index in tracks vector)
- obs const ObsInfo &: Observation information
- Returns void
GetTrackCount - Get track count
- Returns Size: Track count
GetObservationCount - Get observation count of specified track
- track_id PtsId: Track ID
- Returns Size: Observation count
GetObservationByTrackIndex - Get observation by track index
- track_id PtsId: Track ID
- index IndexT: Observation index
- Returns const ObsInfo&: Observation reference
GetValidTrackCount - Get valid track count
- Returns Size: Valid track count
NormalizeTracks - Normalize entire track collection using camera models
- camera_models const CameraModels &: Camera model collection
- Returns bool: Whether normalization succeeded
OriginalizeTracks - Restore normalized tracks to original pixel coordinates using camera models
- camera_models const CameraModels &: Camera model collection
- Returns bool: Whether restoration succeeded
StoreOriginalCoords - Store original coordinates for all observations
- Returns void
ResetToOriginalCoords - Reset all observations to original coordinates
- Returns void
push_back - Add track (compatibility method)
- track const TrackInfo &: Track information
- Returns void
push_back - Add track (move version)
- track TrackInfo &&: Track information
- Returns void
emplace_back - Emplace construct track
- args Args &&...: Construction parameters
- Returns void

Relative Poses (types/relative_poses.hpp)

The relative pose system uses an encapsulation class design, implemented with PIMPL pattern, providing better data security and binary compatibility.

Core Features and Usage Patterns

Encapsulation Design Advantages:

PIMPL Pattern: Hide implementation details, improve binary compatibility
Candidate Solution Support: Support management of multiple candidate pose solutions
Private Member Variables: Prevent accidental modification, improve data security
Public Access Interfaces: Provide unified data access and modification methods
Memory Alignment Optimization: Use Eigen aligned_allocator for improved performance

Typical Usage Examples

Basic Relative Rotation Creation and Operations

using namespace PoSDK::types;

// Create relative rotation
RelativeRotation rel_rot1;  // Default construction
RelativeRotation rel_rot2(0, 1, Matrix3d::Identity(), 1.0f);  // Full parameter construction

// Set and get view IDs
rel_rot1.SetViewIdI(0);
rel_rot1.SetViewIdJ(1);
ViewId view_i = rel_rot1.GetViewIdI();
ViewId view_j = rel_rot1.GetViewIdJ();

// Set and get rotation matrix
Matrix3d R = Matrix3d::Identity();
rel_rot1.SetRotation(R);
Matrix3d R_out = rel_rot1.GetRotation();

// Set and get weight
rel_rot1.SetWeight(0.8f);
float weight = rel_rot1.GetWeight();

// Candidate solution management
rel_rot1.AddCandidateRotation(R);
rel_rot1.AddCandidateRotation(Matrix3d::Identity());
size_t num_candidates = rel_rot1.GetCandidateCount();
Matrix3d candidate_R = rel_rot1.GetCandidateRotation(0);
rel_rot1.SetPrimaryCandidateIndex(1);
size_t primary_idx = rel_rot1.GetPrimaryCandidateIndex();
rel_rot1.ClearCandidates();

Relative Pose Management

// Create relative pose
RelativePose rel_pose1;  // Default construction
RelativePose rel_pose2(0, 1, Matrix3d::Identity(), Vector3d::Zero(), 1.0f);

// Basic accessors
Matrix3d R = rel_pose1.GetRotation();
Vector3d t = rel_pose1.GetTranslation();
rel_pose1.SetRotation(R);
rel_pose1.SetTranslation(t);

// Candidate solution management
rel_pose1.AddCandidate(Matrix3d::Identity(), Vector3d::Zero());
size_t num_candidates = rel_pose1.GetCandidateCount();
Matrix3d candidate_R = rel_pose1.GetCandidateRotation(0);
Vector3d candidate_t = rel_pose1.GetCandidateTranslation(0);

// Pose operations
Matrix3d E = rel_pose1.GetEssentialMatrix();
double rot_err, trans_err;
bool success = rel_pose1.ComputeErrors(rel_pose2, rot_err, trans_err, false);

Relative Pose Collection Management

// Create relative pose collection
RelativePoses poses;

// Add poses
poses.AddPose(rel_pose1);  // Copy add
poses.AddPose(std::move(rel_pose2));  // Move add
poses.EmplacePose(0, 1, Matrix3d::Identity(), Vector3d::Zero(), 1.0f);  // In-place construction

// Access poses
size_t num_poses = poses.size();
const RelativePose* pose_ptr = poses[0];  // Array-style access, returns pointer
if (pose_ptr) {
    Matrix3d R = pose_ptr->GetRotation();
}

// Safe access
try {
    const RelativePose& pose_ref = poses.GetPose(1);  // Reference access, throws exception if out of bounds
    Vector3d t = pose_ref.GetTranslation();
} catch (const std::out_of_range& e) {
    // Handle out-of-bounds access
}

// Iterator access
for (const auto& pose : poses) {
    ViewId i = pose.GetViewIdI();
    ViewId j = pose.GetViewIdJ();
    // Process pose
}

// Specific operations
std::vector<double> rot_errors, trans_errors;
size_t matched = poses.EvaluateAgainst(gt_poses, rot_errors, trans_errors);

Matrix3d R;
Vector3d t;
ViewPair vp(0, 1);
bool found = poses.GetRelativePose(vp, R, t);

`RelativeRotation`

Encapsulated relative rotation class supporting candidate solution management

Private Members (implemented via PIMPL):

Name	Type	Default Value	Purpose
view_id_i	`ViewId`	0	Index of source camera view
view_id_j	`ViewId`	0	Index of target camera view
Rij	`Matrix3d`	Identity matrix	Relative rotation matrix from view i to view j
weight	`float`	1.0f	Weight factor for relative rotation
candidates	`std::vector<Matrix3d>`	Empty vector	Candidate rotation solution collection
primary_candidate_idx	`size_t`	0	Primary candidate solution index

Available Methods:

RelativeRotation - Default constructor
RelativeRotation - Parameterized constructor
- view_id_i ViewId: Source view index
- view_id_j ViewId: Target view index
- Rij const Matrix3d &: Relative rotation matrix (default identity matrix)
- weight float: Weight coefficient (default 1.0f)
GetViewIdI - Get source view ID
GetViewIdJ - Get target view ID
GetRotation - Get rotation matrix
GetWeight - Get weight
SetViewIdI - Set source view ID
- view_id_i ViewId: Source view ID
SetViewIdJ - Set target view ID
- view_id_j ViewId: Target view ID
SetRotation - Set rotation matrix
- Rij const Matrix3d &: Rotation matrix
SetWeight - Set weight
- weight float: Weight value
GetCandidateCount - Get candidate solution count
GetCandidateRotation - Get candidate rotation at specified index
- index size_t: Candidate solution index
AddCandidateRotation - Add candidate rotation solution
- Rij const Matrix3d &: Candidate rotation matrix
SetPrimaryCandidateIndex - Set primary candidate solution index
- index size_t: Candidate solution index
GetPrimaryCandidateIndex - Get primary candidate solution index
ClearCandidates - Clear all candidate solutions

`RelativePose`

Encapsulated relative pose class supporting candidate solution management

Private Members (implemented via PIMPL):

Name	Type	Default Value	Purpose
view_id_i	`ViewId`	0	Index of source camera view
view_id_j	`ViewId`	0	Index of target camera view
Rij	`Matrix3d`	Identity matrix	Relative rotation matrix from view i to view j
tij	`Vector3d`	Zero vector	Relative translation vector from view i to view j
weight	`float`	1.0f	Weight factor for pose estimation
candidates_R	`std::vector<Matrix3d>`	Empty vector	Candidate rotation solution collection
candidates_t	`std::vector<Vector3d>`	Empty vector	Candidate translation solution collection
primary_candidate_idx	`size_t`	0	Primary candidate solution index

Available Methods:

RelativePose - Default constructor
RelativePose - Parameterized constructor
- view_id_i ViewId: Source view index
- view_id_j ViewId: Target view index
- Rij const Matrix3d &: Relative rotation matrix (default identity matrix)
- tij const Vector3d &: Relative translation vector (default zero vector)
- weight float: Weight coefficient (default 1.0f)
GetViewIdI - Get source view ID
GetViewIdJ - Get target view ID
GetRotation - Get rotation matrix
GetTranslation - Get translation vector
GetWeight - Get weight
SetViewIdI - Set source view ID
- view_id_i ViewId: Source view ID
SetViewIdJ - Set target view ID
- view_id_j ViewId: Target view ID
SetRotation - Set rotation matrix
- Rij const Matrix3d &: Rotation matrix
SetTranslation - Set translation vector
- tij const Vector3d &: Translation vector
SetWeight - Set weight
- weight float: Weight value
GetCandidateCount - Get candidate solution count
GetCandidateRotation - Get candidate rotation at specified index
- index size_t: Candidate solution index
GetCandidateTranslation - Get candidate translation at specified index
- index size_t: Candidate solution index
AddCandidate - Add candidate solution
- Rij const Matrix3d &: Candidate rotation matrix
- tij const Vector3d &: Candidate translation vector
SetPrimaryCandidateIndex - Set primary candidate solution index
- index size_t: Candidate solution index
GetPrimaryCandidateIndex - Get primary candidate solution index
ClearCandidates - Clear all candidate solutions
GetEssentialMatrix - Get essential matrix
- Returns Matrix3d: Essential matrix
ComputeErrors - Compute errors with another relative pose
- other const RelativePose &: Another relative pose
- rotation_error double &: Output rotation error (angle)
- translation_error double &: Output translation direction error (angle)
- is_opengv_format bool: Whether OpenGV format (default false)
- Returns bool: Whether computation succeeded

`RelativeRotations`

Relative rotation container class (encapsulation class design, private member variables + public access interfaces)

Available Methods:

size - Get element count
empty - Check if empty
clear - Clear all elements
reserve - Reserve capacity
- n size_t: Reserved size
operator[] - Array-style access (non-const version)
- index size_t: Index
- Returns RelativeRotation*: Rotation pointer, returns nullptr if out of bounds
operator[] - Array-style access (const version)
- index size_t: Index
- Returns const RelativeRotation*: Rotation const pointer, returns nullptr if out of bounds
GetRotation - Get rotation (non-const version)
- index size_t: Index
- Returns RelativeRotation&: Rotation reference (throws exception if out of bounds)
GetRotation - Get rotation (const version)
- index size_t: Index
- Returns const RelativeRotation&: Rotation const reference (throws exception if out of bounds)
AddRotation - Add rotation (copy version)
- rotation const RelativeRotation &: Rotation object
AddRotation - Add rotation (move version)
- rotation RelativeRotation &&: Rotation object
EmplaceRotation - Emplace construct rotation
- args Args &&...: Construction parameters
begin, end - Iterator access
push_back, emplace_back - Compatibility methods

`RelativePoses`

Relative pose container class (encapsulation class design, private member variables + public access interfaces)

Available Methods:

size - Get element count
empty - Check if empty
clear - Clear all elements
reserve - Reserve capacity
- n size_t: Reserved size
operator[] - Array-style access (non-const version)
- index size_t: Index
- Returns RelativePose*: Pose pointer, returns nullptr if out of bounds
operator[] - Array-style access (const version)
- index size_t: Index
- Returns const RelativePose*: Pose const pointer, returns nullptr if out of bounds
GetPose - Get pose (non-const version)
- index size_t: Index
- Returns RelativePose&: Pose reference (throws exception if out of bounds)
GetPose - Get pose (const version)
- index size_t: Index
- Returns const RelativePose&: Pose const reference (throws exception if out of bounds)
AddPose - Add pose (copy version)
- pose const RelativePose &: Pose object
AddPose - Add pose (move version)
- pose RelativePose &&: Pose object
EmplacePose - Emplace construct pose
- args Args &&...: Construction parameters
begin, end - Iterator access
EvaluateAgainst - Evaluate relative pose accuracy
- gt_poses const RelativePoses &: Ground truth relative poses
- rotation_errors std::vector<double> &: Output rotation errors (angle)
- translation_errors std::vector<double> &: Output translation direction errors (angle)
- Returns size_t: Number of matched pose pairs
GetRelativePose - Get relative pose based on ViewPair
- view_pair const ViewPair &: View pair (i,j)
- R Matrix3d &: Output rotation matrix
- t Vector3d &: Output translation vector
- Returns bool: Whether corresponding pose was found
push_back, emplace_back - Compatibility methods

Relative Pose-Related Type Definitions

Type Definitions:

Type	Definition	Default Value	Purpose
`RelativeRotationsPtr`	`std::shared_ptr<RelativeRotations>`	nullptr	Smart pointer type for relative rotation container
`RelativePosesPtr`	`std::shared_ptr<RelativePoses>`	nullptr	Smart pointer type for relative pose container

Utility Functions

Available Methods:

Global2RelativePoses - Convert global poses to relative poses
- global_poses const GlobalPoses &: Input global poses
- relative_poses_output RelativePoses &: Output relative poses
- Returns bool: Whether conversion succeeded

Global Poses (types/global_poses.hpp)

Global Rotation and Translation Types

Type Definitions:

Type	Definition	Description
`GlobalRotations`	`std::vector<Matrix3d, Eigen::aligned_allocator<Matrix3d>>`	Global rotation matrix sequence
`GlobalRotationsPtr`	`std::shared_ptr<GlobalRotations>`	Smart pointer for global rotation sequence
`GlobalTranslations`	`std::vector<Vector3d, Eigen::aligned_allocator<Vector3d>>`	Global translation vector sequence
`GlobalTranslationsPtr`	`std::shared_ptr<GlobalTranslations>`	Smart pointer for global translation sequence

`PoseFormat`

Pose coordinate system format enumeration defining different camera pose representation methods:

Format Definitions:

Format	Formula	Description
`RwTw`	`xc = Rw * (Xw - tw)`	World-to-camera rotation, camera position in world coordinates
`RwTc`	`xc = Rw * Xw + tc`	World-to-camera rotation, translation vector in camera coordinates
`RcTw`	`xc = Rc^T * (Xw - tw)`	Camera-to-camera rotation, camera position in world coordinates
`RcTc`	`xc = Rc^T * Xw + tc`	Camera-to-camera rotation, translation vector in camera coordinates

`EstInfo`

View estimation state information encapsulation class (encapsulation class design, private member variables + public access interfaces), managing view estimation states and ID mapping relationships.

View State Enumeration (ViewState):

INVALID - Invalid or uninitialized view
VALID - Valid view not participating in estimation
ESTIMATED - View that has completed estimation
OPTIMIZED - View that has completed optimization
FILTERED - Filtered view (e.g., outliers)

Private Member Variables:

Name	Type	Default Value	Purpose
`est2origin_id_`	`std::vector<ViewId>`	Empty vector	Estimated ID to original ID mapping (only includes estimated views)
`origin2est_id_`	`std::vector<ViewId>`	Empty vector	Original ID to estimated ID mapping (all views)
`view_states_`	`std::vector<ViewState>`	Empty vector	View state table (all views)

Available Methods:

GetEst2OriginId - Get est2origin_id mapping (const version)
- Returns const std::vector<ViewId>&: Const reference to est2origin_id vector
GetOrigin2EstId - Get origin2est_id mapping (const version)
- Returns const std::vector<ViewId>&: Const reference to origin2est_id vector
GetViewStates - Get view_states table (const version)
- Returns const std::vector<ViewState>&: Const reference to view_states vector
Init - Initialize EstInfo
- num_views size_t: Number of views
AddEstimatedView - Add estimated view
- original_id ViewId: Original view ID
SetViewState - Set view state
- original_id ViewId: Original view ID
- state ViewState: View state
GetViewState - Get view state
- original_id ViewId: Original view ID
IsEstimated - Check if view is estimated
- original_id ViewId: Original view ID
GetNumEstimatedViews - Get number of estimated views
GetViewsInState - Get all view IDs in specific state
- state ViewState: View state
BuildFromTracks - Build EstInfo from Tracks
- tracks_ptr TracksPtr: Track collection smart pointer
- fixed_id ViewId: Fixed view ID
CollectValidViews - Collect valid view IDs
- tracks_ptr TracksPtr: Track collection smart pointer

`GlobalPoses`

Global pose management class (encapsulation class design, private member variables + public access interfaces), storing global pose information for all views

Private Member Variables:

Name	Type	Default Value	Purpose
`rotations_`	`GlobalRotations`	Empty vector	Rotation matrix array for all views
`translations_`	`GlobalTranslations`	Empty vector	Translation vector array for all views
`est_info_`	`EstInfo`	Default value	Estimation state information
`pose_format_`	`PoseFormat`	`RwTw`	Pose format, default is RwTw

Available Methods:

GetRotations - Get rotation matrix collection (const version)
- Returns const GlobalRotations&: Const reference to rotation matrix vector
GetRotations - Get rotation matrix collection (non-const version)
- Returns GlobalRotations&: Reference to rotation matrix vector
GetTranslations - Get translation vector collection (const version)
- Returns const GlobalTranslations&: Const reference to translation vector
GetTranslations - Get translation vector collection (non-const version)
- Returns GlobalTranslations&: Reference to translation vector
Init - Initialize pose data
- num_views size_t: Number of views
GetPoseFormat - Get current pose format
- Returns PoseFormat: Pose format enumeration value
SetPoseFormat - Set pose format
- format PoseFormat: Pose format
GetRotation - Get view rotation matrix (using original ID)
- original_id ViewId: Original view ID
GetTranslation - Get view translation vector (using original ID)
- original_id ViewId: Original view ID
GetRotationByEstId - Get view rotation matrix (using estimated ID)
- est_id ViewId: Estimated view ID
GetTranslationByEstId - Get view translation vector (using estimated ID)
- est_id ViewId: Estimated view ID
SetRotation - Set view rotation matrix
- original_id ViewId: Original view ID
- rotation const Matrix3d&: Rotation matrix
SetTranslation - Set view translation vector
- original_id ViewId: Original view ID
- translation const Vector3d&: Translation vector
SetRotationByEstId - Set rotation using estimated ID
- est_id ViewId: Estimated view ID
- rotation const Matrix3d&: Rotation matrix
SetTranslationByEstId - Set translation using estimated ID
- est_id ViewId: Estimated view ID
- translation const Vector3d&: Translation vector
Size - Get pose count
GetEstInfo - Get EstInfo reference
BuildEstInfoFromTracks - Build EstInfo from Tracks
- tracks_ptr const TracksPtr&: Track collection smart pointer
- fixed_id const ViewId: Fixed view ID (default 0)
ConvertPoseFormat - Member function for converting pose data of current object between different pose formats
- target_format PoseFormat: Target pose format
- ref_id ViewId: Reference view ID (default 0)
- fixed_id ViewId: Fixed view ID (default maximum value)
- Returns bool: Whether conversion succeeded
RwTw_to_RwTc - Member function for converting pose of current object from RwTw to RwTc format
- ref_id ViewId: Reference view ID (default 0)
- fixed_id ViewId: Fixed view ID (default maximum value)
- Returns bool: Whether conversion succeeded
RwTc_to_RwTw - Member function for converting pose of current object from RwTc to RwTw format
- ref_id ViewId: Reference view ID (default 0)
- fixed_id ViewId: Fixed view ID (default maximum value)
- Returns bool: Whether conversion succeeded
EvaluateWithSimilarityTransform - Evaluate pose accuracy using similarity transform
- gt_poses const GlobalPoses &: Ground truth global poses
- rotation_errors std::vector<double> &: Output rotation errors (angle)
- translation_errors std::vector<double> &: Output translation errors
- Returns bool: Whether evaluation succeeded
EvaluateRotations - Evaluate rotation accuracy
- gt_rotations const GlobalRotations &: Ground truth rotation matrices
- rotation_errors std::vector<double> &: Output rotation errors (angle)
- Returns bool: Whether evaluation succeeded
EvaluateRotationsSVD - Evaluate rotation accuracy using SVD method
- gt_rotations const GlobalRotations &: Ground truth rotation matrices
- rotation_errors std::vector<double> &: Output rotation errors (angle)
- Returns bool: Whether evaluation succeeded
NormalizeCameraPositions - Normalize camera positions
- center_before Vector3d &: Center position before normalization
- center_after Vector3d &: Center position after normalization
- Returns bool: Whether normalization succeeded
ComputeCameraPositionCenter - Compute camera position center
- Returns Vector3d: Camera position center vector

Usage Example:

using namespace PoSDK::types;

// Create global pose object
GlobalPoses global_poses;

// Initialize poses for 3 cameras
global_poses.Init(3);

// Set pose format
global_poses.SetPoseFormat(PoseFormat::RwTw);

// Set first camera pose (reference camera, usually identity matrix)
Matrix3d R0 = Matrix3d::Identity();
Vector3d t0 = Vector3d::Zero();
global_poses.SetRotation(0, R0);
global_poses.SetTranslation(0, t0);

// Set second camera pose
Matrix3d R1;
R1 << 0.9998, -0.0174, 0.0087,
      0.0175,  0.9998, -0.0052,
     -0.0087,  0.0052,  1.0000;
Vector3d t1(1.0, 0.0, 0.0);
global_poses.SetRotation(1, R1);
global_poses.SetTranslation(1, t1);

// Set third camera pose
Matrix3d R2;
R2 << 0.9994, -0.0349, 0.0000,
      0.0349,  0.9994, 0.0000,
      0.0000,  0.0000, 1.0000;
Vector3d t2(2.0, 0.0, 0.0);
global_poses.SetRotation(2, R2);
global_poses.SetTranslation(2, t2);

// Mark views as estimated
global_poses.AddEstimatedView(0);
global_poses.AddEstimatedView(1);
global_poses.AddEstimatedView(2);

// Get pose information
const Matrix3d& R_cam1 = global_poses.GetRotation(1);
const Vector3d& t_cam1 = global_poses.GetTranslation(1);

// Check view estimation status
bool is_estimated = global_poses.IsEstimated(1);
size_t num_estimated = global_poses.GetNumEstimatedViews();

// Get all estimated view IDs
std::vector<ViewId> estimated_views = global_poses.GetViewsInState(EstInfo::ViewState::ESTIMATED);

// Pose format conversion
global_poses.ConvertPoseFormat(PoseFormat::RwTc);

// Direct access to rotation and translation vectors (for batch operations)
GlobalRotations& rotations = global_poses.GetRotations();
GlobalTranslations& translations = global_poses.GetTranslations();

// Iterate through all poses
for (size_t i = 0; i < global_poses.Size(); ++i) {
    if (global_poses.IsEstimated(i)) {
        const Matrix3d& R = global_poses.GetRotation(i);
        const Vector3d& t = global_poses.GetTranslation(i);
        // Process pose data...
    }
}

3D Point Cloud Types (types/world_3dpoints.hpp)

Basic 3D Point Type Definitions

Type Definitions:

Type	Definition	Default Value	Purpose
`Points3d`	`Eigen::Matrix<double, 3, Eigen::Dynamic>`	Zero matrix	3D point matrix, 3×N matrix, each column represents a 3D point
`Points3dPtr`	`std::shared_ptr<Points3d>`	nullptr	Smart pointer for 3D point matrix
`Point3d`	`Vector3d`	Zero vector	Single 3D point type

`WorldPointInfo`

3D point information encapsulation class in world coordinates, providing private members and public access interfaces

Private Member Variables:

Name	Type	Default Value	Purpose
`world_points_`	`Points3d`	Zero matrix	World coordinate point collection (3×N matrix)
`ids_used_`	`std::vector<bool>`	Empty vector	Flag array indicating whether points are used
`colors_rgb_`	`std::vector<std::array<uint8_t, 3>>`	Empty vector	RGB color for each point (optional, default empty)

Available Methods:

WorldPointInfo - Default constructor
WorldPointInfo - Constructor initializing specified number of points
- num_points size_t: Number of points
resize - Resize
- num_points size_t: New number of points
size - Get point count
setPoint - Set point coordinates
- index size_t: Point index
- point const Point3d &: 3D point coordinates
getPoint - Get point coordinates
- index size_t: Point index
setUsed - Set point usage status
- index size_t: Point index
- used bool: Whether used
isUsed - Get point usage status
- index size_t: Point index
getValidPointsCount - Get valid point count
operator[] - Array-style access returns pointer (const version)
- index size_t: Point index
- Returns const Vector3d*: Point coordinate pointer, returns nullptr if index is invalid or point is unused
operator[] - Array-style access returns pointer (non-const version)
- index size_t: Point index
- Returns Vector3d*: Point coordinate pointer, returns nullptr if index is invalid or point is unused
GetWorldPoints - Get world coordinate point matrix (const version)
- Returns const Points3d&: Const reference to world coordinate point matrix
GetWorldPoints - Get world coordinate point matrix (non-const version)
- Returns Points3d&: Reference to world coordinate point matrix
GetIdsUsed - Get ids_used vector (const version)
- Returns const std::vector<bool>&: Const reference to ids_used vector
GetIdsUsed - Get ids_used vector (non-const version)
- Returns std::vector<bool>&: Reference to ids_used vector
HasColors - Check if color information exists
- Returns bool: Whether color information exists
GetColorCount - Get color count
- Returns size_t: Color count
GetColorRGB - Get color of specified point
- index size_t: Point index
- Returns const std::array<uint8_t, 3>&: RGB color array
SetColorRGB - Set color of specified point (method 1)
- index size_t: Point index
- r uint8_t: Red component (0-255)
- g uint8_t: Green component (0-255)
- b uint8_t: Blue component (0-255)
- Returns void
SetColorRGB - Set color of specified point (method 2)
- index size_t: Point index
- rgb const std::array<uint8_t, 3>&: RGB color array
- Returns void
InitializeColors - Initialize colors for all points
- Returns void
ClearColors - Clear all color information
- Returns void
GetColorsRGB - Get colors_rgb vector (const version)
- Returns const std::vector<std::array<uint8_t, 3>>&: Const reference to colors_rgb vector
GetColorsRGB - Get colors_rgb vector (non-const version)
- Returns std::vector<std::array<uint8_t, 3>>&: Reference to colors_rgb vector
EvaluateWith3DPoints - Evaluate 3D point reconstruction accuracy
- gt_points const WorldPointInfo &: Ground truth WorldPointInfo
- position_errors std::vector<double> &: Output position errors
- Returns bool: Whether evaluation succeeded

Usage Example:

using namespace PoSDK::types;

// Method 1: Set points after default construction
WorldPointInfo point_cloud;
point_cloud.resize(5);  // Initialize 5 points

// Set point coordinates
point_cloud.setPoint(0, Point3d(1.0, 0.0, 0.0));
point_cloud.setPoint(1, Point3d(0.0, 1.0, 0.0));
point_cloud.setPoint(2, Point3d(0.0, 0.0, 1.0));
point_cloud.setPoint(3, Point3d(1.0, 1.0, 0.0));
point_cloud.setPoint(4, Point3d(1.0, 0.0, 1.0));

// Set point usage status
point_cloud.setUsed(0, true);
point_cloud.setUsed(1, true);
point_cloud.setUsed(2, false);  // Mark 3rd point as unused
point_cloud.setUsed(3, true);
point_cloud.setUsed(4, true);

// Method 2: Specify count during construction
WorldPointInfo point_cloud2(10);  // Directly create 10 points (all enabled by default)

// Get point information
size_t total_points = point_cloud.size();              // Total points: 5
size_t valid_points = point_cloud.getValidPointsCount();  // Valid points: 4

// Get and check single point
Point3d point0 = point_cloud.getPoint(0);
bool is_used = point_cloud.isUsed(2);  // false

// Use operator[] for convenient access (recommended when nullptr check is needed)
const Vector3d* pt0 = point_cloud[0];  // Returns pointer, point exists and is used
if (pt0) {
    std::cout << "Point 0 coordinates: " << pt0->transpose() << std::endl;
    double x = (*pt0)(0);  // Access x coordinate
}

const Vector3d* pt2 = point_cloud[2];  // Returns nullptr, point is unused
if (!pt2) {
    std::cout << "Point 2 is unused, returns nullptr" << std::endl;
}

const Vector3d* pt_invalid = point_cloud[100];  // Returns nullptr, index out of bounds
if (!pt_invalid) {
    std::cout << "Index out of bounds, returns nullptr" << std::endl;
}

// Iterate through all valid points (using operator[])
for (size_t i = 0; i < point_cloud.size(); ++i) {
    const Vector3d* pt = point_cloud[i];
    if (pt) {
        // Process valid point...
        double distance = pt->norm();
    }
}

// Iterate through all valid points (traditional method)
for (size_t i = 0; i < point_cloud.size(); ++i) {
    if (point_cloud.isUsed(i)) {
        Point3d point = point_cloud.getPoint(i);
        // Process valid point...
    }
}

// Direct access to underlying data (for batch operations)
const Points3d& points_matrix = point_cloud.GetWorldPoints();  // 3×N matrix
const std::vector<bool>& usage_flags = point_cloud.GetIdsUsed();

// Batch set point coordinates (efficient way - SIMD optimized)
Points3d& points_ref = point_cloud.GetWorldPoints();
for (int i = 0; i < points_ref.cols(); ++i) {
    points_ref.col(i) = Point3d::Random();  // Set random coordinates
}

// Evaluate reconstruction accuracy (compare with ground truth)
WorldPointInfo gt_points(5);
// ... Set ground truth points ...

std::vector<double> position_errors;
bool success = point_cloud.EvaluateWith3DPoints(gt_points, position_errors);
if (success) {
    // Calculate average error
    double avg_error = 0.0;
    for (double err : position_errors) {
        avg_error += err;
    }
    avg_error /= position_errors.size();
}

3D Point Cloud-Related Type Definitions

Type Definitions:

Type	Definition	Default Value	Purpose
`WorldPointInfoPtr`	`std::shared_ptr<WorldPointInfo>`	nullptr	Smart pointer for world coordinate point information

Similarity Transform (types/similarity_transform.hpp)

Basic Type Definitions

Type Definitions:

Type	Definition	Default Value	Purpose
`CayleyParams`	`Vector3d`	Zero vector	Cayley parameters (3D vector)
`Quaternion`	`Eigen::Vector4d`	Zero vector	Quaternion (4D vector)

`SimilarityTransformError`

Ceres cost function for similarity transform optimization

Available Methods:

SimilarityTransformError - Constructor
- src_point const Vector3d &: Source point
- dst_point const Vector3d &: Target point
operator() - Cost function computation operator
- scale const T *const: Scale parameter
- rotation const T *const: Rotation parameter
- translation const T *const: Translation parameter
- residuals T *: Residual output
Create - Factory function
- src_point const Vector3d &: Source point
- dst_point const Vector3d &: Target point

Similarity Transform Template Functions

Available Methods:

ComputeSimilarityTransform - Template function: Compute optimal similarity transform between two sets of 3D points (using Ceres optimization)
- src_points const PointContainer &: Source point collection
- dst_points const PointContainer &: Target point collection
- src_points_transformed PointContainer &: Transformed source point collection
- scale double &: Output scale factor
- rotation Matrix3d &: Output rotation matrix
- translation Vector3d &: Output translation vector
- Returns bool: Whether succeeded
ComputeSimilarityTransform - Compute optimal similarity transform between two sets of poses (for backward compatibility)
- src_centers const std::vector<Vector3d> &: Source position vectors
- dst_centers const std::vector<Vector3d> &: Target position vectors
- src_centers_transformed std::vector<Vector3d> &: Transformed source position vectors
- scale double &: Output scale factor
- rotation Matrix3d &: Output rotation matrix
- translation Vector3d &: Output translation vector
- Returns bool: Whether succeeded

Mathematical Utility Functions

Available Functions:

CayleyToRotation - Convert Cayley parameters to rotation matrix
- cayley const CayleyParams &: Cayley parameters (3D vector)
- Returns Matrix3d: Rotation matrix
RotationToCayley - Convert rotation matrix to Cayley parameters
- R const Matrix3d &: Rotation matrix
- Returns CayleyParams: Cayley parameters (3D vector)
RelativePoseToParams - Convert relative pose to parameter vector (6 degrees of freedom: 3 rotation + 3 translation)
- pose const RelativePose &: Relative pose
- Returns Eigen::Matrix<double, 6, 1>: 6D parameter vector (first 3 dimensions are Cayley parameters, last 3 are translation)
ParamsToRelativePose - Convert parameter vector to relative pose
- params const Eigen::Matrix<double, 6, 1> &: 6D parameter vector (first 3 dimensions are Cayley parameters, last 3 are translation)
- Returns RelativePose: Relative pose

PoSDK Core Data Types

Modular File Structure

File Organization

Module Responsibilities

Quick Navigation

Fundamental Types Quick Navigation

Camera System Quick Navigation

Image Management Quick Navigation

Feature System Quick Navigation

Matching System Quick Navigation

Track System Quick Navigation

Pose System Quick Navigation

3D Point Cloud System Quick Navigation

Mathematical Transform Quick Navigation

Fundamental Types (types/base.hpp)

Fundamental Identifier Types

Eigen Mathematical Types

Method Configuration Types

Data Package Types

Camera Model (types/camera_model.hpp)

Core Features and Usage Patterns

Typical Usage Examples

Basic Camera Model Creation and Configuration

Intelligent Access to Camera Intrinsics (Recommended Approach)

Multi-Camera Configuration Example

Coordinate Conversion and Distortion Handling

DistortionType

CameraModelType

CameraIntrinsics

CameraModel

CameraModels

Camera Model Related Type Definitions

Image Management (types/image.hpp)

Image Path Type Definitions

Features (types/features.hpp)

Core Features and Usage Patterns

Typical Usage Examples

FeaturePoints Batch Operations (High Performance)

Descriptor Management (SOA Format)

Image Feature Information Management

Feature Collection Management

Fundamental Feature Types

DescriptorsSOA (Recommended)

FeaturePoints (Recommended)

FeaturePoint (Legacy, Retained for Compatibility)

ImageFeatureInfo

FeaturesInfo

Feature-Related Type Definitions

Matching (types/matches.hpp)

IdMatch

Match Collection Type Definitions

Bearing Vector Type Definitions

Bearing Vector Utility Functions

Tracks and Observations (types/tracks.hpp)

Core Features and Usage Patterns

Typical Usage Examples

Basic Observation Information Creation and Operations

Track Information Management

Track Collection Management

ObsInfo

Track

TrackInfo

Tracks

Track-Related Type Definitions

Relative Poses (types/relative_poses.hpp)

Core Features and Usage Patterns

Typical Usage Examples

Basic Relative Rotation Creation and Operations

Relative Pose Management

Relative Pose Collection Management

RelativeRotation

RelativePose

RelativeRotations

RelativePoses

Relative Pose-Related Type Definitions

Utility Functions

Global Poses (types/global_poses.hpp)

Global Rotation and Translation Types

PoseFormat

EstInfo

`DistortionType`

`CameraModelType`

`CameraIntrinsics`

`CameraModel`

`CameraModels`

`DescriptorsSOA` (Recommended)

`FeaturePoints` (Recommended)

`FeaturePoint` (Legacy, Retained for Compatibility)

`ImageFeatureInfo`

`FeaturesInfo`

`IdMatch`

`ObsInfo`

`Track`

`TrackInfo`

`Tracks`

`RelativeRotation`

`RelativePose`

`RelativeRotations`

`RelativePoses`

`PoseFormat`

`EstInfo`

`GlobalPoses`

`WorldPointInfo`

`SimilarityTransformError`