VisionPlus_V3.0/Include/halcon/hlib/HObjectModel3D.h

/*****************************************************************************
 * HObjectModel3D.h
 *****************************************************************************
 *
 * Project:     HALCON/libhalcon
 * Description: Creation and management of 3D object models
 *
 * (c) 2016-2020 by MVTec Software GmbH
 *                  www.mvtec.com
 *
 *****************************************************************************
 */

#ifndef HOBJECTMODEL3D_H
#define HOBJECTMODEL3D_H

#if defined(__cplusplus)
extern "C" {
#endif

/* Creates a new 3D object model with the given handle. */
extern HLibExport Herror HOM3DCreate(Hproc_handle proc_handle,
                                     INT4_8*      object_model);

/* Frees the given 3D object model handle. Note that this function should
 * usually only be called in case of errors during object model creation. Once
 * a handle has been returned to the user, it should be freed outside using the
 * operator  clear_object_model_3d */
extern HLibExport Herror HOM3DFree(Hproc_handle proc_handle,
                                   INT4_8       object_model);

/* Add points to a 3D object model. The points are NOT initialized and must be
 * filled by the caller. The point coordinates are expected in [mm]. */
extern HLibExport Herror HOM3DAddPoints(Hproc_handle proc_handle,
                                        INT4_8 object_model, int num_points,
                                        float** x, float** y, float** z);

/* Add points and a 2D mapping to a 3D object model. The points and the mapping
 * are NOT initialized and must be filled by the caller. The point coordinates
 * are expected in [mm]. */
extern HLibExport Herror HOM3DAddPointsAndMapping(
    Hproc_handle proc_handle, INT4_8 object_model, int num_points, float** x,
    float** y, float** z, HIMGDIM w, HIMGDIM h, HIMGCOOR** br, HIMGCOOR** bc);

/* Add points from non-interleaved XYZ images. The region defines which points
 * are valid. The points are copied into the 3D object model. The values are
 * interpreted as [mm]. */
extern HLibExport Herror HOM3DAddPointsFromImagesRegion(
    Hproc_handle proc_handle, INT4_8 object_model, Hrlregion* region,
    HIMGDIM w, HIMGDIM h, float* x, float* y, float* z);

/* Add points from non-interleaved XYZ images. Points where the z value is
 * identical to the given 'invalid' value are ignored and not added to the 3D
 * object model. The points are copied into the 3D object model. The values are
 * interpreted as [mm]. */
extern HLibExport Herror HOM3DAddPointsFromImagesInvalid(
    Hproc_handle proc_handle, INT4_8 object_model, float invalid, HIMGDIM w,
    HIMGDIM h, float* x, float* y, float* z);

/* Add 2D mappings to a 3D object model. The mappings are NOT initialized and
 * must be filled by the caller. The object model must already contain points,
 * and the number of points must be identical to the number of mappings. */
extern HLibExport Herror HOM3DAddMapping(Hproc_handle proc_handle,
                                         INT4_8 object_model, int num_mappings,
                                         HIMGDIM w, HIMGDIM h, HIMGCOOR** br,
                                         HIMGCOOR** bc);

/* Add normal vectors to a 3D object model. The normals are NOT initialized and
 * must be filled by the caller. The object model must already contain points,
 * and the number of points must be identical to the number of normals. */
extern HLibExport Herror HOM3DAddNormals(Hproc_handle proc_handle,
                                         INT4_8 object_model, int num_normals,
                                         float** nx, float** ny, float** nz);

/* Add triangles to a 3D object model. The triangles are NOT initialized and
 * must be filled by the caller. The 3D obejct model must already contain
 * points. The triangle array has a length of 3*num_triangles, each triangle
 * is represented by three consecutive vertex indices. */
extern HLibExport Herror HOM3DAddTriangles(Hproc_handle proc_handle,
                                           INT4_8       object_model,
                                           int          num_triangles,
                                           int32_t**    triangles);

/* Add a user-defined attribute, which contains one double value per 3D
 * point. The length of the returned array (user_attrib) equals the number
 * of contained 3D points.
 * NOTE that the name of the attribute must start with an ampersand. For
 *      example, "&intensity", "&score", "&red" are valid names. */
extern HLibExport Herror HOM3DAddUserAttrib(Hproc_handle proc_handle,
                                            INT4_8       object_model,
                                            const char*  name,
                                            double**     user_attrib);

/* Returns the list of points contained in the given 3D object model.
 * The point coordinates are returned in [mm]. */
extern HLibExport Herror HOM3DGetPoints(INT4_8 object_model, int* num_points,
                                        float** x, float** y, float** z);

/* Returns the 2D mappings contained in the given 3D object model */
extern HLibExport Herror HOM3DGetMapping(INT4_8 object_model, int* num_points,
                                         HIMGDIM* w, HIMGDIM* h, HIMGCOOR** br,
                                         HIMGCOOR** bc);

/* Returns the point normal vectors contained in the given 3D object model */
extern HLibExport Herror HOM3DGetNormals(INT4_8 object_model, int* num_points,
                                         float** nx, float** ny, float** nz);

/* Returns the triangles contained in the given 3D object model */
extern HLibExport Herror HOM3DGetTriangles(INT4_8 object_model,
                                           int*   num_triangles,
                                           int**  triangles);

/* Returns a user-defined attribute, which contains one double value per 3D
 * point. The length of the returned array (user_attrib) equals the number
 * of contained 3D points. */
extern HLibExport Herror HOM3DGetUserAttrib(INT4_8 object_model,
                                            int* num_points, const char* name,
                                            double** user_attrib);

#if defined(__cplusplus)
}
#endif

#endif /* ifndef HOBJECTMODEL3D_H */