read_object_model_3dT_read_object_model_3dReadObjectModel3dReadObjectModel3d (Operator)


read_object_model_3dT_read_object_model_3dReadObjectModel3dReadObjectModel3d — Read a 3D object model from a file.


read_object_model_3d( : : FileName, Scale, GenParamName, GenParamValue : ObjectModel3D, Status)

Herror T_read_object_model_3d(const Htuple FileName, const Htuple Scale, const Htuple GenParamName, const Htuple GenParamValue, Htuple* ObjectModel3D, Htuple* Status)

void ReadObjectModel3d(const HTuple& FileName, const HTuple& Scale, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* ObjectModel3D, HTuple* Status)

void HObjectModel3D::HObjectModel3D(const HString& FileName, const HTuple& Scale, const HTuple& GenParamName, const HTuple& GenParamValue, HTuple* Status)

void HObjectModel3D::HObjectModel3D(const HString& FileName, const HString& Scale, const HString& GenParamName, const HString& GenParamValue, HString* Status)

void HObjectModel3D::HObjectModel3D(const char* FileName, const char* Scale, const char* GenParamName, const char* GenParamValue, HString* Status)

void HObjectModel3D::HObjectModel3D(const wchar_t* FileName, const wchar_t* Scale, const wchar_t* GenParamName, const wchar_t* GenParamValue, HString* Status)   (Windows only)

HTuple HObjectModel3D::ReadObjectModel3d(const HString& FileName, const HTuple& Scale, const HTuple& GenParamName, const HTuple& GenParamValue)

HString HObjectModel3D::ReadObjectModel3d(const HString& FileName, const HString& Scale, const HString& GenParamName, const HString& GenParamValue)

HString HObjectModel3D::ReadObjectModel3d(const char* FileName, const char* Scale, const char* GenParamName, const char* GenParamValue)

HString HObjectModel3D::ReadObjectModel3d(const wchar_t* FileName, const wchar_t* Scale, const wchar_t* GenParamName, const wchar_t* GenParamValue)   (Windows only)

static void HOperatorSet.ReadObjectModel3d(HTuple fileName, HTuple scale, HTuple genParamName, HTuple genParamValue, out HTuple objectModel3D, out HTuple status)

public HObjectModel3D(string fileName, HTuple scale, HTuple genParamName, HTuple genParamValue, out HTuple status)

public HObjectModel3D(string fileName, string scale, string genParamName, string genParamValue, out string status)

HTuple HObjectModel3D.ReadObjectModel3d(string fileName, HTuple scale, HTuple genParamName, HTuple genParamValue)

string HObjectModel3D.ReadObjectModel3d(string fileName, string scale, string genParamName, string genParamValue)


The operator read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3d reads a 3D object model from the file FileNameFileNameFileNameFileNamefileName and returns a 3D object model handle in ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D.

The operator supports the following file formats:


HALCON format for 3D object model. Files with this format can be written by write_object_model_3dwrite_object_model_3dWriteObjectModel3dWriteObjectModel3dWriteObjectModel3d. The default file extension for this format is 'om3'.


AUTOCAD format. See below for details about reading this file format. The default file extension for this format is 'dxf'.


Object File Format. This is a simple ASCII-based format that can hold 3D points and polygons. The binary OFF format is not supported. The default file extension for this format is 'off'.


Polygon File Format (also Stanford Triangle Format). This is a simple format that can hold 3D points, point normals, polygons, color information and point-based extended attributes. HALCON supports both the ASCII and the binary version of the format. If the file to be read contains unsupported information, the additional data is ignored for ASCII files and only the supported data is read. For binary versions of the format, an error is returned in this case and no object model is returned. The default file extension for this format is 'ply'.


OBJ file format, also 'Wavefront OBJ-Format'. This is an ASCII-based format that can hold 3D points, polygons, normals, texture coordinates, materials and other information. HALCON supports points ('v'-lines) and polygonal faces ('f'-lines). Other entities are ignored. The default file extension for this format is 'obj'.


STL file format, also 'Stereolithography format', 'SurfaceTesselationLanguage ', 'StandardTriangulationLanguage', and 'StandardTesselationLanguage'. This format stores triangles and triangle normals. However, as triangle normals are not supported by HALCON 3D object models, only triangles are read while the triangle normals are ignored. Normals are recomputed from the triangles if required. HALCON reads both the ASCII and the binary version of this format. If 'stl'"stl""stl""stl""stl" is set, HALCON will autodetect the type. Setting the type to 'stl_binary'"stl_binary""stl_binary""stl_binary""stl_binary" or 'stl_ascii'"stl_ascii""stl_ascii""stl_ascii""stl_ascii" will enforce the corresponding format. The default file extension for this format is 'stl'.

When reading a DXF file, the output parameter StatusStatusStatusStatusstatus contains information about the number of 3D faces that were read and, if necessary, warnings that parts of the DXF file could not be interpreted.

The parameter ScaleScaleScaleScalescale defines the scale of the file. For example, if the parameter is set to 'mm'"mm""mm""mm""mm", all units in the file are assumed to have the unit 'mm'"mm""mm""mm""mm" and are transformed into the usual HALCON-internal unit 'm'"m""m""m""m" by multiplication with 1e-3. A value of '100 mm'"100 mm""100 mm""100 mm""100 mm" thus becomes '0.1 m'"0.1 m""0.1 m""0.1 m""0.1 m". Alternatively, a scaling factor can be passed to ScaleScaleScaleScalescale, which is multiplied with all coordinate values found in the file. The relation of units to scaling factors is given in the following table:

Unit Scaling factor
m 1
dm 0.1
cm 0.01
mm 0.001
um, microns 1e-6
nm 1e-9
km 1000
in 0.0254
ft 0.3048
yd 0.9144

Note that the parameter ScaleScaleScaleScalescale is ignored for files of type 'om3'"om3""om3""om3""om3", i.e., om3-files are always read without any scale changes. For changing the scale manually after reading a 3D object model, use affine_trans_object_model_3daffine_trans_object_model_3dAffineTransObjectModel3dAffineTransObjectModel3dAffineTransObjectModel3d.

A set of additional optional parameters can be set. The names and values of the parameters are passed in GenParamNameGenParamNameGenParamNameGenParamNamegenParamName and GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue, respectively. Some of the optional parameters can only be set for a certain file type. The following values for GenParamNameGenParamNameGenParamNameGenParamNamegenParamName are possible:


Forces a file type. If this parameter is not set, the operator read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3d tries to auto-detect the file type using the file ending and the file header. If the parameter is set, the given file is interpreted as this file format.

Value list: 'om3'"om3""om3""om3""om3", 'dxf'"dxf""dxf""dxf""dxf", 'off'"off""off""off""off", 'ply'"ply""ply""ply""ply", 'obj'"obj""obj""obj""obj", 'stl'"stl""stl""stl""stl"


Convert all faces to triangles. If this parameter is set to 'true'"true""true""true""true", all faces read from the file are converted to triangles.

Value list: 'true'"true""true""true""true", 'false'"false""false""false""false"

Default value: 'false'"false""false""false""false"

Valid for formats: 'dxf'"dxf""dxf""dxf""dxf", 'ply'"ply""ply""ply""ply", 'off'"off""off""off""off", 'obj'"obj""obj""obj""obj"


Invert normals and face orientations. If this parameter is set to 'true'"true""true""true""true", the orientation of all normals and faces is inverted.

Value list: 'true'"true""true""true""true", 'false'"false""false""false""false"

Default value: 'false'"false""false""false""false"

Valid for formats: 'dxf'"dxf""dxf""dxf""dxf", 'ply'"ply""ply""ply""ply", 'off'"off""off""off""off", 'obj'"obj""obj""obj""obj", 'stl'"stl""stl""stl""stl"

'max_approx_error'"max_approx_error""max_approx_error""max_approx_error""max_approx_error", 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points":

DXF-specific parameters (see below).

Valid for formats: 'dxf'"dxf""dxf""dxf""dxf"


Creates for the read 3D object model a mapping that assigns an image coordinate to each read 3D point, as in xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3d. It is assumed that the read file contains the 3D points row-wise. The passed value is used as width of the image. The height of the image is computed automatically. If this parameter is set, the read 3D object model can be projected by object_model_3d_to_xyzobject_model_3d_to_xyzObjectModel3dToXyzObjectModel3dToXyzObjectModel3dToXyz using the method 'from_xyz_map'"from_xyz_map""from_xyz_map""from_xyz_map""from_xyz_map". Only one of the two parameters 'xyz_map_width'"xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width" and 'xyz_map_height'"xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height" can be set.

Assertion: 'xyz_map_width'"xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width" > 0 Default value: -1

Valid for formats: 'ply'"ply""ply""ply""ply", 'off'"off""off""off""off", 'obj'"obj""obj""obj""obj"


As 'xyz_map_width'"xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width", but assuming that the 3D points are aligned column-wise. The width of the image is computed automatically. Only one of the two parameters 'xyz_map_width'"xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width" and 'xyz_map_height'"xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height" can be set.

Assertion: 'xyz_map_height'"xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height" > 0 Default value: -1

Valid for formats: 'ply'"ply""ply""ply""ply", 'off'"off""off""off""off", 'obj'"obj""obj""obj""obj"

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_3dsample_object_model_3dSampleObjectModel3dSampleObjectModel3dSampleObjectModel3d, surface_normals_object_model_3dsurface_normals_object_model_3dSurfaceNormalsObjectModel3dSurfaceNormalsObjectModel3dSurfaceNormalsObjectModel3d, or when preparing a 3D object model for surface-based matching, e.g., smoothing, removing outliers, and reducing the domain.

The operator read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3d supports the following DXF entities:

The two-dimensional linear DXF entities LINE, CIRCLE and ARC are not interpreted as faces. Only if these elements are extruded, the resulting faces are inserted in the 3D object model. All elements that represent no faces but lines are added as 3D lines to the 3D object model.

The curved surface of extruded DXF entities of the type CIRCLE and ARC is approximated by planar faces. The accuracy of this approximation can be controlled with the two generic parameters 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points" and 'max_approx_error'"max_approx_error""max_approx_error""max_approx_error""max_approx_error". The parameter 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points" defines the minimum number of sampling points that are used for the approximation of the DXF element CIRCLE or ARC. Note that the parameter 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points" always refers to the full circle, even for ARCs, i.e., if 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points" is set to 50 and a DXF entity of the type ARC is read that represents a semi-circle, this semi-circle is approximated by at least 25 sampling points. The parameter 'max_approx_error'"max_approx_error""max_approx_error""max_approx_error""max_approx_error" defines the maximum deviation of the XLD contour from the ideal circle. The determination of this deviation is carried out in the units used in the DXF file. For the determination of the accuracy of the approximation both criteria are evaluated. Then, the criterion that leads to the more accurate approximation is used.

Internally, the following default values are used for the generic parameters:

To achieve a more accurate approximation, either the value for 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points" must be increased or the value for 'max_approx_error'"max_approx_error""max_approx_error""max_approx_error""max_approx_error" must be decreased.

One possible way to create a suitable DXF file is to create a 3D model of the object with the CAD program AutoCAD. Ensure that the surface of the object is modeled, not only its edges. Lines that, e.g., define object edges, will not be used by HALCON, because they do not define the surface of the object. Once the modeling is completed, you can store the model in DWG format. To convert the DWG file into a DXF file that is suitable for HALCON's 3D matching, carry out the following steps:

Users of other CAD programs should ensure that the surface of the 3D model is triangulated before it is exported into the DXF file. If the CAD program is not able to carry out the triangulation, it is often possible to save the 3D model in the proprietary format of the CAD program and to convert it into a suitable DXF file by using a CAD file format converter that is able to perform the triangulation.

Execution Information

This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.


FileNameFileNameFileNameFileNamefileName (input_control) HTupleHTupleHtuple (string) (string) (HString) (char*)

Filename of the file to be read.

Default value: 'mvtec_bunny_normals' "mvtec_bunny_normals" "mvtec_bunny_normals" "mvtec_bunny_normals" "mvtec_bunny_normals"

Suggested values: 'mvtec_bunny'"mvtec_bunny""mvtec_bunny""mvtec_bunny""mvtec_bunny", 'glass_mug'"glass_mug""glass_mug""glass_mug""glass_mug", 'bmc_mini'"bmc_mini""bmc_mini""bmc_mini""bmc_mini", 'pipe_joint'"pipe_joint""pipe_joint""pipe_joint""pipe_joint", 'clamp_sloped'"clamp_sloped""clamp_sloped""clamp_sloped""clamp_sloped", 'tile_spacer'"tile_spacer""tile_spacer""tile_spacer""tile_spacer"

File extension: .off, .ply, .dxf, .om3, .obj, .stl

ScaleScaleScaleScalescale (input_control)  number HTupleHTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)

Scale of the data in the file.

Default value: 'm' "m" "m" "m" "m"

Suggested values: 'm'"m""m""m""m", 'cm'"cm""cm""cm""cm", 'mm'"mm""mm""mm""mm", 'microns'"microns""microns""microns""microns", 'um'"um""um""um""um", 'nm'"nm""nm""nm""nm", 'km'"km""km""km""km", 'in'"in""in""in""in", 'ft'"ft""ft""ft""ft", 'yd'"yd""yd""yd""yd", 1.0, 0.01, 0.001, 1.0e-6, 0.0254, 0.3048, 0.9144

GenParamNameGenParamNameGenParamNameGenParamNamegenParamName (input_control)  string(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Names of the generic parameters.

Default value: []

List of values: 'convert_to_triangles'"convert_to_triangles""convert_to_triangles""convert_to_triangles""convert_to_triangles", 'file_type'"file_type""file_type""file_type""file_type", 'invert_normals'"invert_normals""invert_normals""invert_normals""invert_normals", 'max_approx_error'"max_approx_error""max_approx_error""max_approx_error""max_approx_error", 'min_num_points'"min_num_points""min_num_points""min_num_points""min_num_points", 'xyz_map_height'"xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height", 'xyz_map_width'"xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width"

GenParamValueGenParamValueGenParamValueGenParamValuegenParamValue (input_control)  string(-array) HTupleHTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)

Values of the generic parameters.

Default value: []

Suggested values: 'true'"true""true""true""true", 'false'"false""false""false""false", 1, 0, 'om3'"om3""om3""om3""om3", 'off'"off""off""off""off", 'ply'"ply""ply""ply""ply", 'dxf'"dxf""dxf""dxf""dxf", 'obj'"obj""obj""obj""obj", 'stl'"stl""stl""stl""stl", 'stl_binary'"stl_binary""stl_binary""stl_binary""stl_binary", 'stl_ascii'"stl_ascii""stl_ascii""stl_ascii""stl_ascii"

ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3D (output_control)  object_model_3d HObjectModel3D, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the 3D object model.

StatusStatusStatusStatusstatus (output_control)  string(-array) HTupleHTupleHtuple (string) (string) (HString) (char*)

Status information.


The operator read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3d returns the value 2 (H_MSG_TRUE) if the given parameters are correct, the file can be read, and the file is valid. If the file format is unknown or cannot be determined, the error 9512 is raised. If the file is invalid, the error 9510 is raised. If necessary, an exception will be raised.

Possible Predecessors


Possible Successors

affine_trans_object_model_3daffine_trans_object_model_3dAffineTransObjectModel3dAffineTransObjectModel3dAffineTransObjectModel3d, object_model_3d_to_xyzobject_model_3d_to_xyzObjectModel3dToXyzObjectModel3dToXyzObjectModel3dToXyz, prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3d



See also

write_object_model_3dwrite_object_model_3dWriteObjectModel3dWriteObjectModel3dWriteObjectModel3d, clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dClearObjectModel3d


3D Metrology