Skip to content

prepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dprepare_object_model_3dT_prepare_object_model_3d🔗

Short description🔗

prepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dprepare_object_model_3dT_prepare_object_model_3d — Prepare a 3D object model for a certain operation.

Signature🔗

prepare_object_model_3d( object_model_3d ObjectModel3D, string Purpose, string OverwriteData, attribute.name GenParamName, attribute.value GenParamValue )void PrepareObjectModel3d( const HTuple& ObjectModel3D, const HTuple& Purpose, const HTuple& OverwriteData, const HTuple& GenParamName, const HTuple& GenParamValue )static void HOperatorSet.PrepareObjectModel3d( HTuple objectModel3D, HTuple purpose, HTuple overwriteData, HTuple genParamName, HTuple genParamValue )def prepare_object_model_3d( object_model_3d: MaybeSequence[HHandle], purpose: str, overwrite_data: str, gen_param_name: Sequence[Union[str, float, int]], gen_param_value: Sequence[Union[str, float, int]] ) -> None

Herror T_prepare_object_model_3d( const Htuple ObjectModel3D, const Htuple Purpose, const Htuple OverwriteData, const Htuple GenParamName, const Htuple GenParamValue )

static void HObjectModel3D::PrepareObjectModel3d( const HObjectModel3DArray& ObjectModel3D, const HString& Purpose, const HString& OverwriteData, const HTuple& GenParamName, const HTuple& GenParamValue )

void HObjectModel3D::PrepareObjectModel3d( const HString& Purpose, const HString& OverwriteData, const HTuple& GenParamName, const HTuple& GenParamValue ) const

void HObjectModel3D::PrepareObjectModel3d( const char* Purpose, const char* OverwriteData, const HTuple& GenParamName, const HTuple& GenParamValue ) const

void HObjectModel3D::PrepareObjectModel3d( const wchar_t* Purpose, const wchar_t* OverwriteData, const HTuple& GenParamName, const HTuple& GenParamValue ) const (Windows only)

static void HObjectModel3D.PrepareObjectModel3d( HObjectModel3D[] objectModel3D, string purpose, string overwriteData, HTuple genParamName, HTuple genParamValue )

void HObjectModel3D.PrepareObjectModel3d( string purpose, string overwriteData, HTuple genParamName, HTuple genParamValue )

Description🔗

The operator prepare_object_model_3dPrepareObjectModel3d prepares the 3D object model ObjectModel3DobjectModel3Dobject_model_3d for a following operation given in Purposepurposepurpose. It computes values required for the operation and stores them in ObjectModel3DobjectModel3Dobject_model_3d, thus speeding up the following operation. It is not necessary to call prepare_object_model_3dPrepareObjectModel3d. However, if the 3D object model is to be used multiple times for the same operation, it can be faster to do so.

The following values are possible for Purposepurposepurpose:

  • 'shape_based_matching_3d'"shape_based_matching_3d": The 3D object model is prepared to be used in create_shape_model_3dCreateShapeModel3d. For this, there are no generic parameters to set.

  • 'segmentation'"segmentation": The 3D object model is prepared to be used in segment_object_model_3dSegmentObjectModel3d. For the preparation the 3D object model must have an attribute with the face triangles and an attribute with the 3D point coordinates.

    If the 3D object model has no attribute with the face triangles, a simple triangulation is performed (even if OverwriteDataoverwriteDataoverwrite_data is set to 'false'"false"). For this, the 3D object model must have an attribute with the 3D point coordinates and an attribute with the mapping from the point coordinates to image coordinates. Only points originating from neighboring pixels are triangulated. Additionally, holes in the image region can be filled with a Delaunay triangulation (see 'max_area_holes'"max_area_holes" below). Only holes which are completely surrounded by the image region are closed.

  • 'distance_computation'"distance_computation": The 3D object model is prepared to be used in distance_object_model_3dDistanceObjectModel3d.

  • 'gen_xyz_mapping'"gen_xyz_mapping": The XYZ-mapping information of a 3D object model containing an ordered point cloud is computed, i.e. image coordinates are assigned for each 3D point. For this, either the generic parameter 'xyz_map_width'"xyz_map_width" or 'xyz_map_height'"xyz_map_height" must be set, to indicate whether the point cloud is ordered row-wise or column-wise and define the image dimensions (see 'xyz_map_width'"xyz_map_width" and 'xyz_map_height'"xyz_map_height" below).

    Note that in many cases, it is recommended to use the 2D mapping data, if available, for speed and robustness reasons. This is beneficial especially when using sample_object_model_3dSampleObjectModel3d, surface_normals_object_model_3dSurfaceNormalsObjectModel3d, or when preparing a 3D object model for surface-based matching, e.g., smoothing, removing outliers, and reducing the domain.

The parameter OverwriteDataoverwriteDataoverwrite_data defines if the existing data of an already prepared 3D object model shall be removed. If OverwriteDataoverwriteDataoverwrite_data is set to 'true'"true", the prepared data, defined with the parameter Purposepurposepurpose, is overwritten. If OverwriteDataoverwriteDataoverwrite_data is set to 'false'"false", the prepared data is not overwritten. If there is no prepared data OverwriteDataoverwriteDataoverwrite_data is ignored and data is saved in a 3D object model. The parameter OverwriteDataoverwriteDataoverwrite_data can be used for choosing another set of generic parameters GenParamNamegenParamNamegen_param_name and GenParamValuegenParamValuegen_param_value. The parameter OverwriteDataoverwriteDataoverwrite_data has no influence if the parameter Purposepurposepurpose is set to 'shape_based_matching_3d'"shape_based_matching_3d", because for that, there are no generic parameters to set.

The generic parameters can optionally be used to influence the preparation. If desired, these parameters and their corresponding values can be specified by using GenParamNamegenParamNamegen_param_name and GenParamValuegenParamValuegen_param_value, respectively. The following values for GenParamNamegenParamNamegen_param_name are possible:

  • 'max_area_holes'"max_area_holes": This parameter is only valid if Purposepurposepurpose is set to 'segmentation'"segmentation". The parameter specifies which area holes of the point coordinates are closed during a simple Delaunay triangulation. Only holes which are completely surrounded by the image region are closed. If 'max_area_holes'"max_area_holes" is set to 00, no holes are triangulated. If the parameter 'max_area_holes'"max_area_holes" is set greater or equal than 11 pixel, the holes with an area less or equal than 'max_area_holes'"max_area_holes" are closed by a meshing.

    Suggested values: 11, 1010, 100100.

    Default: 1010.

  • 'distance_to'"distance_to": This parameter is only valid if Purposepurposepurpose is set to 'distance_computation'"distance_computation". The parameter specifies the type of data to which the distance shall be computed to. It is described in more detail in the documentation of distance_object_model_3dDistanceObjectModel3d.

    List of values: 'auto'"auto", 'triangles'"triangles", 'points'"points", 'primitive'"primitive".

    Default: 'auto'"auto".

  • 'method'"method": This parameter is only valid if Purposepurposepurpose is set to 'distance_computation'"distance_computation". The parameter specifies the method to be used for the distance computation. It is described in more detail in the documentation of distance_object_model_3dDistanceObjectModel3d.

    List of values: 'auto'"auto", 'kd-tree'"kd-tree", 'voxel'"voxel", 'linear'"linear".

    Default: 'auto'"auto".

  • 'max_distance'"max_distance": This parameter is only valid if Purposepurposepurpose is set to 'distance_computation'"distance_computation". The parameter specifies the maximum distance of interest for the distance computation. If it is set to 00, no maximum distance is used. It is described in more detail in the documentation of distance_object_model_3dDistanceObjectModel3d.

    Suggested values: 00, 0.10.1, 11, 1010.

    Default: 00.

  • 'sampling_dist_rel'"sampling_dist_rel": This parameter is only valid if Purposepurposepurpose is set to 'distance_computation'"distance_computation". The parameter specifies the relative sampling distance when computing the distance to triangles with the method 'voxel'"voxel". It is described in more detail in the documentation of distance_object_model_3dDistanceObjectModel3d.

    Suggested values: 0.030.03, 0.010.01.

    Default: 0.030.03.

  • 'sampling_dist_abs'"sampling_dist_abs": This parameter is only valid if Purposepurposepurpose is set to 'distance_computation'"distance_computation". The parameter specifies the absolute sampling distance when computing the distance to triangles with the method 'voxel'"voxel". It is described in more detail in the documentation of distance_object_model_3dDistanceObjectModel3d.

    Suggested values: 11, 55, 1010.

    Default: None.

  • 'xyz_map_width'"xyz_map_width": This parameter is only valid if Purposepurposepurpose is set to 'gen_xyz_mapping'"gen_xyz_mapping". The parameter indicates that the point cloud is ordered row-wise and the passed value is used as the width of the image. The height of the image is calculated automatically. Only one of the two parameters 'xyz_map_width'"xyz_map_width" and 'xyz_map_height'"xyz_map_height" can be set.

    Default: None.

  • 'xyz_map_height'"xyz_map_height": This parameter is only valid if Purposepurposepurpose is set to 'gen_xyz_mapping'"gen_xyz_mapping". The parameter indicates that the point cloud is ordered column-wise and the passed value is used as the height of the image. The width of the image is calculated automatically. Only one of the two parameters 'xyz_map_width'"xyz_map_width" and 'xyz_map_height'"xyz_map_height" can be set.

    Default: None.

Execution information🔗

Execution information

  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).

  • Multithreading scope: global (may be called from any thread).

  • Processed without parallelization.

Parameters🔗

ObjectModel3DobjectModel3Dobject_model_3d (input_control) object_model_3d(-array) → (handle)HTuple (HHandle)HObjectModel3D, HTuple (IntPtr)MaybeSequence[HHandle]Htuple (handle)

Handle of the 3D object model.

Purposepurposepurpose (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Purpose of the 3D object model.

Default: 'shape_based_matching_3d'"shape_based_matching_3d"
Suggested values: 'shape_based_matching_3d', 'segmentation', 'distance_computation', 'gen_xyz_mapping'"shape_based_matching_3d", "segmentation", "distance_computation", "gen_xyz_mapping"

OverwriteDataoverwriteDataoverwrite_data (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Specify if already existing data should be overwritten.

Default: 'true'"true"
List of values: 'false', 'true'"false", "true"

GenParamNamegenParamNamegen_param_name (input_control) attribute.name-array → (string / real / integer)HTuple (HString / double / Hlong)HTuple (string / double / int / long)Sequence[Union[str, float, int]]Htuple (char* / double / Hlong)

Names of the generic parameters.

Default: [][]
List of values: 'distance_to', 'max_area_holes', 'max_distance', 'method', 'sampling_dist_abs', 'sampling_dist_rel', 'xyz_map_height', 'xyz_map_width'"distance_to", "max_area_holes", "max_distance", "method", "sampling_dist_abs", "sampling_dist_rel", "xyz_map_height", "xyz_map_width"

GenParamValuegenParamValuegen_param_value (input_control) attribute.value-array → (string / real / integer)HTuple (HString / double / Hlong)HTuple (string / double / int / long)Sequence[Union[str, float, int]]Htuple (char* / double / Hlong)

Values of the generic parameters.

Default: [][]
Suggested values: 0, 1, 100, 'auto', 'triangles', 'points', 'primitive', 'kd-tree', 'voxel', 'linear', 0.01, 0.030, 1, 100, "auto", "triangles", "points", "primitive", "kd-tree", "voxel", "linear", 0.01, 0.03

Example🔗

(HDevelop)

read_object_model_3d ('object_model_3d', 'm', [], [], ObjectModel3D, Status)
prepare_object_model_3d (ObjectModel3D, 'gen_xyz_mapping', 'true',\
                         'xyz_map_width', Width)
object_model_3d_to_xyz (X, Y, Z, ObjectModel3D, 'from_xyz_map', [], [])

Result🔗

The operator prepare_object_model_3dPrepareObjectModel3d returns the value 2 (H_MSG_TRUE) if the given parameters are correct. Otherwise, an exception will be raised.

Combinations with other operators🔗

Combinations

Possible predecessors

read_object_model_3dReadObjectModel3d, xyz_to_object_model_3dXyzToObjectModel3d

Possible successors

create_shape_model_3dCreateShapeModel3d, create_surface_modelCreateSurfaceModel, distance_object_model_3dDistanceObjectModel3d, find_surface_modelFindSurfaceModel, fit_primitives_object_model_3dFitPrimitivesObjectModel3d, refine_surface_model_poseRefineSurfaceModelPose, segment_object_model_3dSegmentObjectModel3d, simplify_object_model_3dSimplifyObjectModel3d, sample_object_model_3dSampleObjectModel3d, surface_normals_object_model_3dSurfaceNormalsObjectModel3d

Module🔗

3D Metrology