tango_3d_reconstruction_api.h

Go to the documentation of this file.

// Copyright 2016 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef TANGO_3D_RECONSTRUCTION_API_TANGO_3D_RECONSTRUCTION_API_H_
#define TANGO_3D_RECONSTRUCTION_API_TANGO_3D_RECONSTRUCTION_API_H_

#include <stdbool.h>
#include <stdint.h>


#ifdef __cplusplus
extern "C" {
#endif


typedef enum {
  TANGO_3DR_ERROR = -3,
  TANGO_3DR_INSUFFICIENT_SPACE = -2,
  TANGO_3DR_INVALID = -1,
  TANGO_3DR_SUCCESS = 0
} Tango3DR_Status;

typedef enum {
  TANGO_3DR_HAL_PIXEL_FORMAT_RGBA_8888 = 1,         
  TANGO_3DR_HAL_PIXEL_FORMAT_RGB_888 = 3,           
  TANGO_3DR_HAL_PIXEL_FORMAT_YCrCb_420_SP = 0x11,   
  TANGO_3DR_HAL_PIXEL_FORMAT_DEPTH16 = 0x44363159,  
} Tango3DR_ImageFormatType;

typedef enum {
  TANGO_3DR_CALIBRATION_UNKNOWN = 0,
  TANGO_3DR_CALIBRATION_EQUIDISTANT = 1,
  TANGO_3DR_CALIBRATION_POLYNOMIAL_2_PARAMETERS = 2,
  TANGO_3DR_CALIBRATION_POLYNOMIAL_3_PARAMETERS = 3,
  TANGO_3DR_CALIBRATION_POLYNOMIAL_5_PARAMETERS = 4,
} Tango3DR_TangoCalibrationType;

typedef enum {
  TANGO_3DR_CONFIG_RECONSTRUCTION = 0,
  TANGO_3DR_CONFIG_TEXTURING = 1
} Tango3DR_ConfigType;

typedef enum {
  TANGO_3DR_CPU_TEXTURING = 0,
  TANGO_3DR_GL_TEXTURING = 1,
} Tango3DR_TexturingBackend;

typedef enum {
  TANGO_3DR_TRAVERSAL_UPDATE = 0,
  TANGO_3DR_PROJECTIVE_UPDATE = 1,
} Tango3DR_UpdateMethod;

typedef enum {
  TANGO_3DR_CAMERA_COLOR = 0,    
  TANGO_3DR_CAMERA_IR = 1,       
  TANGO_3DR_CAMERA_FISHEYE = 2,  
  TANGO_3DR_CAMERA_DEPTH = 3,    
} Tango3DR_CameraId;



typedef struct _Tango3DR_ReconstructionContext* Tango3DR_ReconstructionContext;

typedef struct _Tango3DR_TexturingContext* Tango3DR_TexturingContext;

typedef struct _Tango3DR_Config* Tango3DR_Config;

typedef struct _Tango3DR_Trajectory* Tango3DR_Trajectory;

typedef struct _Tango3DR_AreaDescription* Tango3DR_AreaDescription;

typedef float Tango3DR_Vector3[3];

typedef float Tango3DR_Vector4[4];

typedef uint32_t Tango3DR_Face[3];

typedef uint8_t Tango3DR_Color[4];

typedef int Tango3DR_GridIndex[3];

typedef int Tango3DR_GridIndex2D[2];

typedef float Tango3DR_TexCoord[2];

typedef struct Tango3DR_CameraCalibration {
  Tango3DR_TangoCalibrationType calibration_type;

  uint32_t width;
  uint32_t height;

  double fx;
  double fy;
  double cx;
  double cy;

  double distortion[5];
} Tango3DR_CameraCalibration;

typedef struct Tango3DR_Pose {
  double translation[3];

  double orientation[4];
} Tango3DR_Pose;

typedef struct Tango3DR_Matrix3x3 {
  double data[9];
} Tango3DR_Matrix3x3;

typedef struct Tango3DR_SignedDistanceVoxel {
  int16_t sdf;
  uint16_t weight;
} Tango3DR_SignedDistanceVoxel;

typedef struct Tango3DR_GridIndexArray {
  uint32_t num_indices;

  Tango3DR_GridIndex* indices;
} Tango3DR_GridIndexArray;

typedef struct Tango3DR_PointCloud {
  double timestamp;

  uint32_t num_points;

  Tango3DR_Vector4* points;
} Tango3DR_PointCloud;

typedef struct Tango3DR_ImageBuffer {
  uint32_t width;
  uint32_t height;
  uint32_t stride;
  double timestamp;
  Tango3DR_ImageFormatType format;
  uint8_t* data;
} Tango3DR_ImageBuffer;

typedef struct Tango3DR_Mesh {
  double timestamp;

  uint32_t num_vertices;

  uint32_t num_faces;

  uint32_t num_textures;

  uint32_t max_num_vertices;

  uint32_t max_num_faces;

  uint32_t max_num_textures;  // Capacity of the texture array.

  Tango3DR_Vector3* vertices;

  Tango3DR_Face* faces;

  Tango3DR_Vector3* normals;

  Tango3DR_Color* colors;

  Tango3DR_TexCoord* texture_coords;

  int32_t* texture_ids;

  Tango3DR_ImageBuffer* textures;
} Tango3DR_Mesh;

typedef struct Tango3DR_FloorplanLevel {
  float min_z;

  float max_z;
} Tango3DR_FloorplanLevel;

typedef struct Tango3DR_FloorplanLevelArray {
  uint32_t num_levels;

  Tango3DR_FloorplanLevel* levels;
} Tango3DR_FloorplanLevelArray;

typedef float Tango3DR_Vector2[2];

typedef enum {
  TANGO_3DR_LAYER_SPACE = 0,
  TANGO_3DR_LAYER_WALLS,
  TANGO_3DR_LAYER_FURNITURE,
  TANGO_3DR_LAYER_OBSTACLES
} Tango3DR_FloorplanLayer;

typedef struct Tango3DR_Polygon {
  uint32_t num_vertices;

  bool closed;

  Tango3DR_FloorplanLayer layer;

  Tango3DR_Vector2* vertices;  // In meters.

  double area;  // In square meters.
} Tango3DR_Polygon;

typedef struct Tango3DR_PolygonArray {
  uint32_t num_polygons;

  Tango3DR_Polygon* polygons;
} Tango3DR_PolygonArray;

Tango3DR_Status Tango3DR_PointCloud_init(const uint32_t num_points,
                                         Tango3DR_PointCloud* cloud);

Tango3DR_Status Tango3DR_PointCloud_initEmpty(Tango3DR_PointCloud* cloud);

Tango3DR_Status Tango3DR_PointCloud_destroy(Tango3DR_PointCloud* cloud);

Tango3DR_Status Tango3DR_PointCloud_saveToPly(const Tango3DR_PointCloud* cloud,
                                              const char* const path);

Tango3DR_Status Tango3DR_PointCloud_loadFromPly(const char* const path,
                                                Tango3DR_PointCloud* cloud);

Tango3DR_Status Tango3DR_CameraCalibration_initEmpty(
    Tango3DR_CameraCalibration* calibration);

Tango3DR_Status Tango3DR_CameraCalibration_loadFromDataset(
    Tango3DR_CameraId camera_id, const char* const dataset_path,
    Tango3DR_CameraCalibration* calibration);

Tango3DR_Status Tango3DR_ImageBuffer_initEmpty(Tango3DR_ImageBuffer* image);

Tango3DR_Status Tango3DR_ImageBuffer_init(uint32_t width, uint32_t height,
                                          Tango3DR_ImageFormatType format,
                                          Tango3DR_ImageBuffer* image);

Tango3DR_Status Tango3DR_ImageBuffer_destroy(Tango3DR_ImageBuffer* image);

Tango3DR_Status Tango3DR_ImageBuffer_saveToPnm(
    const Tango3DR_ImageBuffer* image, const char* const path);

Tango3DR_Status Tango3DR_ImageBuffer_saveToPng(
    const Tango3DR_ImageBuffer* image, const char* const path);

Tango3DR_Status Tango3DR_ImageBuffer_loadFromPnm(const char* const path,
                                                 Tango3DR_ImageBuffer* image);

Tango3DR_Status Tango3DR_ImageBuffer_loadFromPng(const char* const path,
                                                 Tango3DR_ImageBuffer* image);

Tango3DR_Status Tango3DR_Mesh_initEmpty(Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_Mesh_init(
    const uint32_t vertices_capacity, const uint32_t faces_capacity,
    const bool allocate_normals, const bool allocate_colors,
    const bool allocate_tex_coords, const bool allocate_tex_ids,
    const uint32_t textures_capacity, const uint32_t textures_width,
    const uint32_t textures_height, Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_Mesh_loadFromObj(const char* const path,
                                          Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_Mesh_saveToObj(const Tango3DR_Mesh* mesh,
                                        const char* const path);

Tango3DR_Status Tango3DR_Mesh_destroy(Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_GridIndexArray_init(
    const uint32_t num_indices, Tango3DR_GridIndexArray* grid_index_array);

Tango3DR_Status Tango3DR_GridIndexArray_initEmpty(
    Tango3DR_GridIndexArray* grid_index_array);

Tango3DR_Status Tango3DR_GridIndexArray_destroy(
    Tango3DR_GridIndexArray* grid_index_array);

//
//
//
Tango3DR_Status Tango3DR_PointCloudToRectifiedDepthImage(
    const Tango3DR_PointCloud* cloud,
    const Tango3DR_CameraCalibration* depth_camera_calibration,
    Tango3DR_ImageBuffer* image);



Tango3DR_Config Tango3DR_Config_create(Tango3DR_ConfigType config_type);

Tango3DR_Status Tango3DR_Config_destroy(Tango3DR_Config config);

Tango3DR_Status Tango3DR_Config_setBool(Tango3DR_Config config, const char* key,
                                        bool value);

Tango3DR_Status Tango3DR_Config_setInt32(Tango3DR_Config config,
                                         const char* key, int32_t value);

Tango3DR_Status Tango3DR_Config_setInt64(Tango3DR_Config config,
                                         const char* key, int64_t value);

Tango3DR_Status Tango3DR_Config_setDouble(Tango3DR_Config config,
                                          const char* key, double value);

Tango3DR_Status Tango3DR_Config_setMatrix3x3(Tango3DR_Config config,
                                             const char* key,
                                             const Tango3DR_Matrix3x3* value);

Tango3DR_Status Tango3DR_Config_getBool(const Tango3DR_Config config,
                                        const char* key, bool* value);

Tango3DR_Status Tango3DR_Config_getInt32(const Tango3DR_Config config,
                                         const char* key, int32_t* value);

Tango3DR_Status Tango3DR_Config_getInt64(const Tango3DR_Config config,
                                         const char* key, int64_t* value);

Tango3DR_Status Tango3DR_Config_getDouble(const Tango3DR_Config config,
                                          const char* key, double* value);

Tango3DR_Status Tango3DR_Config_getMatrix3x3(Tango3DR_Config config,
                                             const char* key,
                                             Tango3DR_Matrix3x3* value);



Tango3DR_ReconstructionContext Tango3DR_ReconstructionContext_create(
    const Tango3DR_Config context_config);

Tango3DR_Status Tango3DR_ReconstructionContext_destroy(
    Tango3DR_ReconstructionContext context);

Tango3DR_Status Tango3DR_clear(Tango3DR_ReconstructionContext context);

Tango3DR_Status Tango3DR_updateFromPointCloud(
    Tango3DR_ReconstructionContext context, const Tango3DR_PointCloud* cloud,
    const Tango3DR_Pose* cloud_pose, const Tango3DR_ImageBuffer* color_image,
    const Tango3DR_Pose* color_image_pose,
    Tango3DR_GridIndexArray* updated_indices);

Tango3DR_Status Tango3DR_updateFromDepthImage(
    Tango3DR_ReconstructionContext context,
    const Tango3DR_ImageBuffer* depth_image,
    const Tango3DR_Pose* depth_image_pose,
    const Tango3DR_ImageBuffer* color_image,
    const Tango3DR_Pose* color_image_pose,
    Tango3DR_GridIndexArray* updated_indices);

Tango3DR_Status Tango3DR_getActiveIndices(
    const Tango3DR_ReconstructionContext context,
    Tango3DR_GridIndexArray* active_indices);

Tango3DR_Status Tango3DR_getGridSegmentBoundingBox(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndex grid_index, Tango3DR_Vector3* corner_min,
    Tango3DR_Vector3* corner_max);

Tango3DR_Status Tango3DR_getMeshSegmentBoundingBox(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndex grid_index, Tango3DR_Vector3* corner_min,
    Tango3DR_Vector3* corner_max);

Tango3DR_Status Tango3DR_extractMeshSegment(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndex grid_index, Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_extractPreallocatedMeshSegment(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndex grid_index, Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_extractMesh(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndexArray* grid_index_array, Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_extractPreallocatedMesh(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndexArray* grid_index_array, Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_extractFullMesh(
    const Tango3DR_ReconstructionContext context, Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_extractPreallocatedFullMesh(
    const Tango3DR_ReconstructionContext context, Tango3DR_Mesh* mesh);

Tango3DR_Status Tango3DR_extractPreallocatedVoxelGridSegment(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndex grid_index, const int num_sdf_voxels,
    Tango3DR_SignedDistanceVoxel* sdf_voxels);

Tango3DR_Status Tango3DR_ReconstructionContext_decimatePlanes(
    const Tango3DR_ReconstructionContext context, const double min_plane_area,
    Tango3DR_Mesh* tango_mesh);

Tango3DR_Status Tango3DR_ReconstructionContext_setDepthCalibration(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_CameraCalibration* calibration);

Tango3DR_Status Tango3DR_ReconstructionContext_setColorCalibration(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_CameraCalibration* calibration);

Tango3DR_Status Tango3DR_CameraCalibration_rescale(
    const int new_width, const int new_height,
    Tango3DR_CameraCalibration* calibration_to_rescale);



Tango3DR_TexturingContext Tango3DR_TexturingContext_create(
    const Tango3DR_Config texture_config, const Tango3DR_Mesh* tango_mesh);

Tango3DR_Status Tango3DR_TexturingContext_destroy(
    Tango3DR_TexturingContext context);

Tango3DR_Status Tango3DR_TexturingContext_setColorCalibration(
    const Tango3DR_TexturingContext context,
    const Tango3DR_CameraCalibration* calibration);

Tango3DR_Status Tango3DR_updateTexture(Tango3DR_TexturingContext context,
                                       const Tango3DR_ImageBuffer* image,
                                       const Tango3DR_Pose* image_pose);

Tango3DR_Status Tango3DR_updateTextureGl(Tango3DR_TexturingContext context,
                                         const int texture_target,
                                         const int image_texture_id,
                                         const Tango3DR_Pose* image_pose);

Tango3DR_Status Tango3DR_getTexturedMesh(
    const Tango3DR_TexturingContext context, Tango3DR_Mesh* tango_mesh_out);



Tango3DR_Status Tango3DR_extractLevels(
    const Tango3DR_ReconstructionContext context,
    Tango3DR_FloorplanLevelArray* levels);

Tango3DR_Status Tango3DR_resetLevelsEstimator(
    const Tango3DR_ReconstructionContext context);

Tango3DR_Status Tango3DR_selectLevel(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_FloorplanLevel* level);

void Tango3DR_destroyLevels(Tango3DR_FloorplanLevelArray* levels);

Tango3DR_Status Tango3DR_updateFullFloorplan(
    const Tango3DR_ReconstructionContext context);

Tango3DR_Status Tango3DR_updateFloorplan(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndexArray* grid_index_array);

Tango3DR_Status Tango3DR_extractFullFloorplan(
    const Tango3DR_ReconstructionContext context,
    Tango3DR_PolygonArray* graphics);

Tango3DR_Status Tango3DR_extractFloorplanSegment(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndex2D grid_index, Tango3DR_PolygonArray* graphics);

Tango3DR_Status Tango3DR_extractFullFloorplanImage(
    const Tango3DR_ReconstructionContext context, Tango3DR_FloorplanLayer layer,
    Tango3DR_Vector2* origin, Tango3DR_ImageBuffer* image);

Tango3DR_Status Tango3DR_extractFloorplanImageSegment(
    const Tango3DR_ReconstructionContext context,
    const Tango3DR_GridIndex2D grid_index, Tango3DR_FloorplanLayer layer,
    Tango3DR_ImageBuffer* image);

void Tango3DR_VectorGraphics_destroy(Tango3DR_PolygonArray* graphics);



Tango3DR_Status Tango3DR_AreaDescription_destroy(
    Tango3DR_AreaDescription area_description);

Tango3DR_Status Tango3DR_AreaDescription_saveToAdf(
    Tango3DR_AreaDescription area_description, const char* const path);

Tango3DR_Status Tango3DR_AreaDescription_loadFromAdf(
    const char* const path, Tango3DR_AreaDescription* area_description);

Tango3DR_Status Tango3DR_Trajectory_createFromAreaDescription(
    const Tango3DR_AreaDescription area_description,
    Tango3DR_Trajectory* trajectory);

Tango3DR_Status Tango3DR_Trajectory_destroy(Tango3DR_Trajectory trajectory);

Tango3DR_Status Tango3DR_Trajectory_getEarliestTime(
    const Tango3DR_Trajectory trajectory, double* timestamp);

Tango3DR_Status Tango3DR_Trajectory_getLatestTime(
    const Tango3DR_Trajectory trajectory, double* timestamp);

Tango3DR_Status Tango3DR_getPoseAtTime(const Tango3DR_Trajectory trajectory,
                                       const double timestamp,
                                       Tango3DR_Pose* tango_pose);



typedef void (*Tango3DR_ProgressCallback)(int progress, void* callback_param);

Tango3DR_Status Tango3DR_AreaDescription_createFromDataset(
    const char* dataset_path, const char* loop_closure_database_path,
    Tango3DR_AreaDescription* area_description,
    Tango3DR_ProgressCallback progress_callback, void* callback_param);

Tango3DR_Status Tango3DR_updateFromTrajectoryAndDataset(
    const Tango3DR_ReconstructionContext context, const char* dataset_path,
    const Tango3DR_Trajectory trajectory,
    Tango3DR_ProgressCallback progress_callback, void* callback_param);

Tango3DR_Status Tango3DR_textureMeshFromDataset(
    const Tango3DR_Config texture_config, const char* dataset_path,
    const Tango3DR_Trajectory trajectory, const Tango3DR_Mesh* tango_mesh_in,
    Tango3DR_Mesh* tango_mesh_out, Tango3DR_ProgressCallback progress_callback,
    void* callback_param);

// TODO(idryanov): Add link to documentation.
Tango3DR_Status Tango3DR_extractRawDataFromDataset(
    const char* dataset_path, const char* output_path,
    Tango3DR_ProgressCallback progress_callback, void* callback_param);


#ifdef __cplusplus
}
#endif

#endif  // TANGO_3D_RECONSTRUCTION_API_TANGO_3D_RECONSTRUCTION_API_H_