read_object_model_3d_dxf — Read a 3D object model from a DXF file.
read_object_model_3d_dxf is obsolete and is only provided for reasons of backward compatibility. New applications should use the operator read_object_model_3d instead.
The operator read_object_model_3d_dxf reads the contents of the DXF file FileName (DXF version AC1009, AutoCAD Release 12) and converts them to a 3D object model. The handle of the 3D object model is returned in ObjectModel3D. If no absolute path is given in FileName, the DXF file is searched in the current directory of the HALCON process. The default HALCON file extension for the DXF file is 'dxf'.
The output parameter DxfStatus 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 operator read_object_model_3d_dxf supports the following DXF entities:
Polyface meshes (Polyline flag 64)
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.
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' and 'max_approx_error'. The parameter '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' always refers to the full circle, even for ARCs, i.e., if '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' 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:
'min_num_points' = 20
'max_approx_error' = 0.25
To achieve a more accurate approximation, either the value for 'min_num_points' must be increased or the value for '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 modelled, 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 modelling 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:
Export the 3D CAD model to a 3DS file using the 3dsout command of AutoCAD. This will triangulate the object's surface, i.e., the model will only consist of planes. (Users of AutoCAD 2007 or newer versions can download this command utility from Autodesk's web site.)
Open a new empty sheet in AutoCAD.
Import the 3DS file into this empty sheet with the 3dsin command of AutoCAD.
Save the object into a DXF R12 file.
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.
Note that if a 3D object model is no longer needed or should be overwritten, the memory has to be freed first by calling the operator clear_object_model_3d.
Name of the DXF file
File extension: .dxf
Scale or unit.
Default value: 'm'
Suggested values: 'm', 'cm', 'mm', 'microns', 'µm', 1.0, 0.01, 0.001, 1.0e-6, 0.0254, 0.3048, 0.9144
Names of the generic parameters that can be adjusted for the DXF input.
Default value: 
List of values: 'max_approx_error', 'min_num_points'
Values of the generic parameters that can be adjusted for the DXF input.
Default value: 
Suggested values: 0.1, 0.25, 0.5, 1, 2, 5, 10, 20
Handle of the read 3D object model.
read_object_model_3d_dxf returns 2 (H_MSG_TRUE) if all parameters are correct. If necessary, an exception is raised.
affine_trans_object_model_3d, project_object_model_3d, clear_object_model_3d