PhoXi3DMeshingApi

The main entry point of the 3D Meshing library. Provides tools for automatic or semi-automatic meshing of small objects using PhoXi 3D scanners.

Constants

const auto p3dm_api::INVALID_INDEX = uint32_t(-1)

Invalid index.

const auto p3dm_api::INVALID_DEVICE_CONNECTION = ConnectedDeviceId(std::string())

Invalid device connection.

Types

using p3dm_api::ConnectedDeviceId = utils::StrongType<std::string, class PhoXi3DMeshingApi>

The id of a connected device.

Main Class

class PhoXi3DMeshingApi

This class provides tools suitable for automatic or semi-automatic meshing of small objects using PhoXi 3D scanners.

Public Functions

explicit PhoXi3DMeshingApi(std::ostream &log_stream = std::cout)

Constructor of PhoXi3DMeshingApi class.

Parameters:

log_stream – Output stream for log messages.

~PhoXi3DMeshingApi()

Destructor of PhoXi3DMeshingApi class. Disconnects from all devices in PhoXiControl connected through this API.

ConnectedDeviceId ConnectDevice(const std::string &device_id, bool keep_connected = false)

Connects PhoXi device using PhoXiControl software and accepts it as secondary.

Note

If this is the primary device, SetPrimaryDevice must be called to set it up as such.

Parameters:

  • device_id – PhoXi device identifier.

  • keep_connected – If true, the device will keep connected after the object is destroyed.

Returns:

Returns identifier of a connected PhoXi device or INVALID_DEVICE_CONNECTION.

bool DisconnectDevice(const ConnectedDeviceId &device_id)

Disconnects and removes a device from device setup.

Note

If this is the primary device, all secondary devices will be flagged as “unused” - not disconnected in PhoXiControl software, but not used any longer in PhoXi3DMeshing.

Parameters:

device_id – Identifier of a connected PhoXi device that is to be removed.

Returns:

Returns true if disconnection has been successful.

bool SetPrimaryDevice(const ConnectedDeviceId &device_id)

Sets PhoXi device as primary.

Parameters:

device_id – Identifier of a connected PhoXi device.

Returns:

Returns true if successful.

std::vector<ConnectedDeviceId> GetUnusedDeviceIds() const

Get ids of all connected PhoXiControl devices that P3DM no longer uses.

Returns:

A vector of connected device ids.

bool CalibratePrimaryDevice(const std::shared_ptr<turntables::Table> &table)

Calibrates device setup between a primary device and a rotary table using a marker board.

Note

The marker board must be placed on the rotary table and must be clearly visible from the primary device.

Returns:

Returns true if device setup calibration has been successful.

bool CalibrateSecondaryDevice(const ConnectedDeviceId &device_id)

Uses an already connected secondary device and calibrates it to a primary device using marker board.

Note

The marker board must be clearly visible from both devices.

Parameters:

device_id – Identifier of a connected PhoXi device.

Returns:

Returns true if there is a connected primary device to calibrate to, if this device is connected to and calibration has been successful.

bool StopUsingDevice(const ConnectedDeviceId &device_id)

Set device state to be “unused”. Device will stay connected in the PhoXiControl.

Note

If this is the primary device, all secondary devices will be flagged as “unused” as well.

Parameters:

device_id – Identifier of a connected PhoXi device that is to be stopped using.

Returns:

Returns true if the operation has been successful.

bool LoadDevicesSetup(const std::string &file_path, bool keep_connected = false)

Imports a device setup calibration from a JSON file.

Parameters:

  • file_path – Path to the calibration file.

  • keep_connected – If true, all connected devices will keep connected after the object is destroyed.

Returns:

Returns true if the setup has been loaded and applied successfully.

bool SaveDevicesSetup(const std::string &file_path)

Exports a device setup calibration into a JSON file.

Returns:

Returns true if the setup has been saved successfully.

std::vector<uint32_t> CaptureScansAuto(const std::shared_ptr<turntables::Table> &table, const turntables::RotationParams &rotation_params, bool preserve_table_starting_position = true, bool phoxi_device_mode_change_is_allowed = true, const std::function<void()> &on_scanning_finished = {})

Captures scans automatically for each rotary table position using PhoXiControl software.

Note

Primary and secondary devices setup (if any secondary device is used) must be calibrated before running this method.

Parameters:

  • table – Turn table controller.

  • rotation_params – Rotation parameters that specify rotation angles. Can be initialized with a number of rotations in the case of a fully circular rotation.

  • preserve_table_starting_position – If true, a turn table is rotated back to its starting position after scans are captured.

  • phoxi_device_mode_change_is_allowed – If true, PhoXi settings may be changed.

  • on_scanning_finished – Function that will be called when scanning is finished.

Returns:

Returns IDs of added scans. Returns empty vector, if the method fails.

std::vector<uint32_t> CaptureScansAutoTrimmed(const std::shared_ptr<turntables::Table> &table, const turntables::RotationParams &rotation_params, const p3dm_api::settings::RotableBackgroundRemoval &settings = {}, bool preserve_table_starting_position = true, bool phoxi_device_mode_change_is_allowed = true, const std::function<void()> &on_scanning_finished = {})

Captures scans automatically for each rotary table position using PhoXiControl. Automatically removes background points from scans.

Note

Captured object must be placed on the rotary table. Primary and secondary devices setup (if any secondary device is used) must be calibrated before running this method.

Parameters:

  • table – Turn table controller.

  • rotation_params – Rotation parameters that specify rotation angles. Can be initialized with a number of rotations in the case of a fully circular rotation.

  • settings – Optional parameters adjusting background points removal.

  • preserve_table_starting_position – If true, a turn table is rotated back to its starting position after scans are captured.

  • phoxi_device_mode_change_is_allowed – If true, PhoXi settings may be changed.

  • on_scanning_finished – Function that will be called when scanning is finished.

Returns:

Returns IDs of added scans. Returns empty vector, if the method fails.

std::vector<uint32_t> CaptureScansManual(float ground_filter_offset = 0.0f)

Captures scans using PhoXiControl software and a marker board.

Note

The marker board must be visible from the primary device during a data capture. If any secondary device is used, the device setup must be calibrated before running this method.

Parameters:

ground_filter_offset – Up direction offset in marker space for ground filtering.

Returns:

Returns IDs of added scans. Returns empty vector, if method fails.

uint32_t ImportScan(const std::string &file_path)

Import scan data from a file.

Note

Supported input file extensions: .cogs, .praw, .ply.

Parameters:

file_path – Full directory including filename and file extension.

Returns:

Returns an ID of imported scan. Returns p3dm::INVALID_INDEX if import has failed.

bool ExportScan(uint32_t id, const std::string &file_path, settings::Export settings = {}) const

Export scan with specific ID to file.

Note

Supported output file extensions: .cogs, .ply.

Parameters:

  • id – ID of exported scan.

  • file_path – Full directory including filename and file extension.

  • settings – Optional parameters adjusting export options.

Returns:

Returns true if export has been successful.

bool ExportUnionPointCloud(const std::string &file_path, settings::UnionCreation settings = {}, settings::Export export_settings = {}) const

Export all scans into a single unorganized point cloud file.

Note

Supported output file extensions: .cogs, .ply.

Parameters:

  • file_path – Full directory including filename and file extension.

  • settings – Optional point cloud postprocessing properties.

  • export_settings – Optional parameters adjusting export options.

Returns:

Returns true if export has been successful.

bool ExportUnionPointCloud(const std::string &file_path, const std::vector<uint32_t> &ids, settings::UnionCreation settings = {}, settings::Export export_settings = {}) const

Export a subset of scans into a single unorganized point cloud file.

Note

Supported output file extensions: .cogs, .ply.

Parameters:

  • file_path – Full directory including filename and file extension.

  • ids – Vector of scan IDs to be included in export.

  • settings – Optional point cloud union creation properties.

  • export_settings – Optional parameters adjusting export options.

Returns:

Returns true if export has been successful.

uint32_t AddScan(const pho::api::PFrame &scan, const pho::api::PhoXiCalibrationSettings &calib_settings = {})

Adds new scan to default scan set.

Note

This method does not detect marker board.

Parameters:

  • scan – Scan data.

  • calib_settings – [Deprecated] Calibration settings needed for further scan processing. This argument is no longer needed and will not be used.

Returns:

Returns ID of imported scan. Returns p3dm::INVALID_INDEX if import has failed.

bool RemoveScan(uint32_t id)

Removes scan with specific ID from vector of scans.

Returns:

Returns false if ID does not exist.

bool RemoveAllScans()

Removes all scans.

pho::api::PFrame GetPhoXiScan(uint32_t id) const

Get specific scan with calibration settings.

Returns:

Returns specific scan with input id. If scan with the id do not exist, returns nullptr.

std::vector<pho::api::PFrame> GetPhoXiScans() const

Get all scans.

Returns:

Returns a vector of scans.

std::vector<pho::api::PFrame> GetPhoXiScans(const std::vector<uint32_t> &ids) const

Get a subset of scans.

Parameters:

ids – Vector of scan IDs to be included in result.

Returns:

Returns a vector of scans.

std::pair<pho::api::PFrame, pho::api::PhoXiCalibrationSettings> GetScan(uint32_t id) const

[Deprecated] - use GetPhoXiScan instead. Get specific scan with calibration settings.

Returns:

Returns specific scan with input id along with calibration settings. If scan with the id do not exist, returns pair with nullptr and blank calibration settings.

std::vector<std::pair<pho::api::PFrame, pho::api::PhoXiCalibrationSettings>> GetScans() const

[Deprecated] - use GetPhoXiScans instead. Get all scans.

Returns:

Returns a vector of scans with corresponding calibration settings.

std::vector<std::pair<pho::api::PFrame, pho::api::PhoXiCalibrationSettings>> GetScans(const std::vector<uint32_t> &ids) const

[Deprecated] - use GetPhoXiScans instead. Get a subset of scans.

Parameters:

ids – Vector of scan IDs to be included in result.

Returns:

Returns a vector of scans with corresponding calibration settings.

std::shared_ptr<PointCloud> GetUnionPointCloud(settings::UnionCreation settings = {}) const

Create a single unorganized point cloud from a all scans.

Parameters:

settings – Optional postprocessing properties.

Returns:

Returns an unorganized point cloud.

std::shared_ptr<ColoredPointCloud> GetColoredUnionPointCloud(settings::UnionCreation settings = {}) const

Create a single colored unorganized point cloud from a all scans.

Parameters:

settings – Optional postprocessing properties.

Returns:

Returns an unorganized point cloud with colors.

std::shared_ptr<PointCloud> GetUnionPointCloud(const std::vector<uint32_t> &ids, settings::UnionCreation settings = {}) const

Create a single unorganized point cloud from a subset of scans.

Parameters:

  • ids – Vector of scan IDs to be included in export.

  • settings – Optional postprocessing properties.

Returns:

Returns an unorganized point cloud.

std::shared_ptr<ColoredPointCloud> GetColoredUnionPointCloud(const std::vector<uint32_t> &ids, settings::UnionCreation settings = {}) const

Create a single colored unorganized point cloud from a subset of scans.

Parameters:

  • ids – Vector of scan IDs to be included in export.

  • settings – Optional postprocessing properties.

Returns:

Returns an unorganized point cloud with colors.

std::vector<std::pair<uint32_t, glm::mat4>> AlignScans(const p3dm_api::settings::Alignment &settings = {})

Align all scans using Skeletex ICP.

Note

Method is designed to increase accuracy of initial alignment.

Parameters:

settings – Optional parameters adjusting alignment precision and convergence.

Returns:

Returns an vector of pairs, where the first value is id of scan and the second is corresponding result transformation matrix.

std::vector<std::pair<uint32_t, glm::mat4>> AlignScans(const std::vector<uint32_t> &ids, const p3dm_api::settings::Alignment &settings = {})

Align a subset of scans using Skeletex ICP.

Note

Method is designed to increase accuracy of initial alignment.

Parameters:

  • ids – Vector of scan IDs to be aligned.

  • settings – Optional parameters adjusting alignment precision and convergence.

Returns:

Returns an vector of pairs, where the first value is id of scan and the second is corresponding result transformation matrix.

bool AlignScanSets(const std::vector<uint32_t> &base_scan_set_scan_ids, const std::vector<uint32_t> &align_scan_set_scan_ids, const p3dm_api::settings::Registration &settings = {})

Align specified sets of scans using PCL registration.

Parameters:

  • base_scan_set_scan_ids – Scan IDs of base scan set.

  • align_scan_set_scan_ids – Scan IDs of the scan set to be aligned to base.

  • settings – Optional parameters adjusting alignment options.

Returns:

Returns success.

void TransformScan(const glm::mat4 &transformation, const uint32_t id)

Apply transformation.

Parameters:

  • transformation – Transformation matrix.

  • id – ID of transformed scan.

glm::mat4 GetScanTransformation(uint32_t id) const

Returns transformation for specific scan. Transformation is cumulated through all calls of AlignScans and TransformScan.

std::vector<std::pair<uint32_t, glm::mat4>> GetScansTransformations() const

Returns an vector of pairs for all scans, where the first value is id of scan and the second is corresponding transformation matrix. Transformations are cumulated through all calls of AlignScans and TransformScan.

std::vector<std::pair<uint32_t, glm::mat4>> GetScansTransformations(const std::vector<uint32_t> &ids) const

Returns an vector of pairs for subset of scans, where the first value is id of scan and the second is corresponding transformation matrix. Transformations are cumulated through all calls of AlignScans and TransformScan.

std::vector<uint32_t> GetAllScanIds() const

Returns a vector of IDs of all scans. Returns empty vector, if method fails.

void CropScanWithBoundingBox(const Aabb &aabb, uint32_t id)

For specific scan, removes all points outside of supplemented axis aligned bounding box.

Parameters:

  • id – ID of cropped scan.

  • aabb – Axis aligned bounding box.

void CropScansWithBoundingBox(const Aabb &aabb)

For all scans, removes all points outside of supplemented axis aligned bounding box.

Parameters:

aabb – Axis aligned bounding box.

void CropScansWithBoundingBox(const Aabb &aabb, const std::vector<uint32_t> &ids)

For specific scans, removes all points outside of supplemented axis aligned bounding box.

Parameters:

  • ids – IDs of cropped scans.

  • aabb – Axis aligned bounding box.

bool FilterScans(const p3dm_api::settings::Filtering &settings = {})

Crosschecks data of all scans and removes invalid points.

Parameters:

settings – Optional parameters adjusting filtering strictness.

Returns:

Returns true if filtering has been successful.

bool FilterScans(const std::vector<uint32_t> &ids, const p3dm_api::settings::Filtering &settings = {})

Crosschecks data of subset of scans and removes invalid points.

Parameters:

  • ids – Vector of scan IDs to be crosschecked and filtered.

  • settings – Optional parameters adjusting filtering strictness.

Returns:

Returns true if filtering has been successful.

bool CreateMesh(const std::string &poisson_recon_path, const p3dm_api::settings::Reconstruction &settings = {})

Create mesh from all scans.

Parameters:

  • poisson_recon_path – Path to Poisson reconstruction program.

  • settings – Optional parameters adjusting meshing precision.

Returns:

Returns true if meshing has been successful.

bool CreateMesh(const std::vector<uint32_t> &ids, const std::string &poisson_recon_path, const p3dm_api::settings::Reconstruction &settings = {})

Create mesh from subset of scans.

Parameters:

  • ids – Vector of scan IDs to be meshed.

  • poisson_recon_path – Path to Poisson reconstruction program.

  • settings – Optional parameters adjusting meshing precision.

Returns:

Returns true if meshing has been successful.

bool TrimMesh(const std::optional<float> &trim_distance = std::nullopt)

Removes parts of surface introduced by meshing method.

Parameters:

trim_distance – Maximal distance between triangle centroid and original point cloud from which was mesh reconstructed. Lower values cause more triangles to be removed during mesh trimming. If not set, value is estimated automatically.

Returns:

Returns true if trimming has been successful.

Mesh GetMesh() const

Returns mesh.

Note

Mesh must be created before calling this method.

ColoredMesh GetColoredMesh() const

Returns colored mesh.

Note

Mesh must be created before calling this method.

bool ExportMesh(const std::string &file_path, settings::Export settings = {}) const

Save mesh to a file.

Note

Mesh must be created before calling this method. Supported output file extensions: .cogs, .stl, .fbx, .ply.

Parameters:

  • file_path – Full directory including filename and file extension.

  • settings – Optional parameters adjusting export options.

void Clear()

Removes a mesh, scans, a device setup calibration and disconnects all devices.

void CopyDevicesFromP3DM(const PhoXi3DMeshingApi &other)

Copy all connected device handles with calibrations from other instance of PhoXi3DMeshingApi.