read_object_model_3dT_read_object_model_3dReadObjectModel3dReadObjectModel3dread_object_model_3d (算子)
名称
read_object_model_3dT_read_object_model_3dReadObjectModel3dReadObjectModel3dread_object_model_3d — 从文件中读取三维对象模型。
签名
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)
def read_object_model_3d(file_name: str, scale: Union[str, float, int], gen_param_name: MaybeSequence[str], gen_param_value: MaybeSequence[Union[str, float, int]]) -> Tuple[HHandle, Sequence[str]]
def read_object_model_3d_s(file_name: str, scale: Union[str, float, int], gen_param_name: MaybeSequence[str], gen_param_value: MaybeSequence[Union[str, float, int]]) -> Tuple[HHandle, str]
描述
算子 read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3dread_object_model_3d reads a 3D object model from
the file FileNameFileNameFileNameFileNamefileNamefile_name and returns a 3D object model handle in
ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d。
The operator supports the following file formats:
- 'om3'"om3""om3""om3""om3""om3"：
HALCON format for 3D object model. Files with this format can be
written by write_object_model_3dwrite_object_model_3dWriteObjectModel3dWriteObjectModel3dWriteObjectModel3dwrite_object_model_3d。The default file extension for this format is 'om3'.
- 'dxf'"dxf""dxf""dxf""dxf""dxf"：
AUTOCAD format.
HALCON supports only the ASCII version of the format.
See below for details about reading this file format.
The default file extension for this format is 'dxf'.
- 'off'"off""off""off""off""off"：
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'.
- 'ply'"ply""ply""ply""ply""ply"：
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 and only the supported data is read.
If the name of a property entry of a 'ply' file coincides with
the name of a standard
attribute (see set_object_model_3d_attribset_object_model_3d_attribSetObjectModel3dAttribSetObjectModel3dAttribSetObjectModel3dAttribset_object_model_3d_attrib), the property will
preferably be read into the standard attribute.
The default file extension for this format is 'ply'.
- 'obj'"obj""obj""obj""obj""obj"：
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), point normals ('vn'-lines) and
polygonal faces ('f'-lines).
Existing point normals are only returned if there are exactly as many
point normals as there are points.
Other entities are ignored.
The default file extension for this format is 'obj'.
- 'stl'"stl""stl""stl""stl""stl",
-
- 'stl_binary'"stl_binary""stl_binary""stl_binary""stl_binary""stl_binary",
-
- 'stl_ascii'"stl_ascii""stl_ascii""stl_ascii""stl_ascii""stl_ascii"：
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""stl" is set, HALCON will auto-detect the type. Setting the
type to 'stl_binary'"stl_binary""stl_binary""stl_binary""stl_binary""stl_binary" or 'stl_ascii'"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 StatusStatusStatusStatusstatusstatus 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 ScaleScaleScaleScalescalescale defines the scale of the file. For example,
if the parameter is set to 'mm'"mm""mm""mm""mm""mm", all units in the file are
assumed to have the unit 'mm'"mm""mm""mm""mm""mm" and are transformed into the
usual HALCON-internal unit 'm'"m""m""m""m""m" by multiplication with 1e-3.
A value of '100 mm'"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""0.1 m".
Alternatively, a scaling factor can be passed to ScaleScaleScaleScalescalescale, 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 ScaleScaleScaleScalescalescale is ignored for files of type
'om3'"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_3dAffineTransObjectModel3dAffineTransObjectModel3dAffineTransObjectModel3daffine_trans_object_model_3d。
A set of additional optional parameters can be set. The names and values
of the parameters are passed in GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name and
GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value, respectively. Some of the optional parameters
can only be set for a certain file type.GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name 的可能取值如下：
- 'file_type'"file_type""file_type""file_type""file_type""file_type"：
-
Forces a file type.
If this parameter is not set, the operator
read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3dread_object_model_3d 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.
值列表：
'om3'"om3""om3""om3""om3""om3", 'dxf'"dxf""dxf""dxf""dxf""dxf",
'off'"off""off""off""off""off", 'ply'"ply""ply""ply""ply""ply",
'obj'"obj""obj""obj""obj""obj", 'stl'"stl""stl""stl""stl""stl".
- 'convert_to_triangles'"convert_to_triangles""convert_to_triangles""convert_to_triangles""convert_to_triangles""convert_to_triangles"：
-
Convert all faces to triangles.
If this parameter is set to 'true'"true""true""true""true""true", all faces read from
the file are converted to triangles.
Valid for formats: 'dxf'"dxf""dxf""dxf""dxf""dxf", 'ply'"ply""ply""ply""ply""ply",
'off'"off""off""off""off""off", 'obj'"obj""obj""obj""obj""obj".
值列表：
'true'"true""true""true""true""true", 'false'"false""false""false""false""false".
默认值：
'false'"false""false""false""false""false".
- 'invert_normals'"invert_normals""invert_normals""invert_normals""invert_normals""invert_normals"：
-
Invert normals and face orientations.
If this parameter is set to 'true'"true""true""true""true""true", the orientation of
all normals and faces is inverted.
Valid for formats: 'dxf'"dxf""dxf""dxf""dxf""dxf", 'ply'"ply""ply""ply""ply""ply",
'off'"off""off""off""off""off", 'obj'"obj""obj""obj""obj""obj",
'stl'"stl""stl""stl""stl""stl".
值列表：
'true'"true""true""true""true""true", 'false'"false""false""false""false""false".
默认值：
'false'"false""false""false""false""false".
- 'max_approx_error'"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""min_num_points"：
-
DXF-specific parameters (see below).
Valid for formats: 'dxf'"dxf""dxf""dxf""dxf""dxf".
- 'xyz_map_width'"xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width"：
-
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_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3dxyz_to_object_model_3d。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_xyzObjectModel3dToXyzObjectModel3dToXyzObjectModel3dToXyzobject_model_3d_to_xyz using the method
'from_xyz_map'"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""xyz_map_width" and
'xyz_map_height'"xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height" can be set.
Valid for formats: 'ply'"ply""ply""ply""ply""ply", 'off'"off""off""off""off""off",
'obj'"obj""obj""obj""obj""obj".
默认值：
-1.
限制：
'xyz_map_width'"xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width" > 0
- 'xyz_map_height'"xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height"：
-
As 'xyz_map_width'"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""xyz_map_width" and
'xyz_map_height'"xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height" can be set.
Valid for formats: 'ply'"ply""ply""ply""ply""ply", 'off'"off""off""off""off""off",
'obj'"obj""obj""obj""obj""obj".
默认值：
-1.
限制：
'xyz_map_height'"xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height""xyz_map_height" > 0
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_3dSampleObjectModel3dSampleObjectModel3dSampleObjectModel3dsample_object_model_3d,
surface_normals_object_model_3dsurface_normals_object_model_3dSurfaceNormalsObjectModel3dSurfaceNormalsObjectModel3dSurfaceNormalsObjectModel3dsurface_normals_object_model_3d, or when preparing a 3D object
model for surface-based matching, e.g., smoothing, removing outliers, and
reducing the domain.
算子 read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3dread_object_model_3d supports the following
DXF entities:
-
POLYLINE
-
Polyface meshes (Polyline flag 64)
-
3D Polylines (Polyline flag 8,9)
-
2D Polylines (Polyline flag 0)
-
LWPOLYLINE
-
3DFACE
-
LINE
-
CIRCLE
-
ARC
-
SOLID
-
BLOCK
-
INSERT
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""min_num_points" and
'max_approx_error'"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""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""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""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""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'"min_num_points""min_num_points""min_num_points""min_num_points""min_num_points" = 20
-
'max_approx_error'"max_approx_error""max_approx_error""max_approx_error""max_approx_error""max_approx_error" = 0.25
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""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""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:
-
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.
执行信息
- 多线程类型：可重入（与非独占算子并行运行）。
- 多线程作用域：全局（可从任何线程调用）。
- 未采用并行化处理。
此算子返回一个句柄。请注意，即使该句柄被用作特定算子的输入参数，这些算子仍可能改变此句柄类型的实例状态。
参数
FileNameFileNameFileNameFileNamefileNamefile_name (输入控制) filename.read → HTuplestrHTupleHtuple (string) (string) (HString) (char*)
Filename of the file to be read.
默认值：
'mvtec_bunny_normals'
"mvtec_bunny_normals"
"mvtec_bunny_normals"
"mvtec_bunny_normals"
"mvtec_bunny_normals"
"mvtec_bunny_normals"
建议值：
'mvtec_bunny'"mvtec_bunny""mvtec_bunny""mvtec_bunny""mvtec_bunny""mvtec_bunny", 'glass_mug'"glass_mug""glass_mug""glass_mug""glass_mug""glass_mug", 'bmc_mini'"bmc_mini""bmc_mini""bmc_mini""bmc_mini""bmc_mini", 'pipe_joint'"pipe_joint""pipe_joint""pipe_joint""pipe_joint""pipe_joint", 'clamp_sloped'"clamp_sloped""clamp_sloped""clamp_sloped""clamp_sloped""clamp_sloped", 'tile_spacer'"tile_spacer""tile_spacer""tile_spacer""tile_spacer""tile_spacer"
File extension:
.off, .ply, .dxf, .om3, .obj, .stl
ScaleScaleScaleScalescalescale (输入控制) number → HTupleUnion[str, float, int]HTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)
Scale of the data in the file.
默认值：
'm'
"m"
"m"
"m"
"m"
"m"
建议值：
'm'"m""m""m""m""m", 'cm'"cm""cm""cm""cm""cm", 'mm'"mm""mm""mm""mm""mm", 'microns'"microns""microns""microns""microns""microns", 'um'"um""um""um""um""um", 'nm'"nm""nm""nm""nm""nm", 'km'"km""km""km""km""km", 'in'"in""in""in""in""in", 'ft'"ft""ft""ft""ft""ft", 'yd'"yd""yd""yd""yd""yd", 1.0, 0.01, 0.001, 1.0e-6, 0.0254, 0.3048, 0.9144
GenParamNameGenParamNameGenParamNameGenParamNamegenParamNamegen_param_name (输入控制) string(-array) → HTupleMaybeSequence[str]HTupleHtuple (string) (string) (HString) (char*)
通用参数的名称。
默认值：
[]
值列表：
'convert_to_triangles'"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""file_type", 'invert_normals'"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""max_approx_error", 'min_num_points'"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_height", 'xyz_map_width'"xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width""xyz_map_width"
GenParamValueGenParamValueGenParamValueGenParamValuegenParamValuegen_param_value (输入控制) string(-array) → HTupleMaybeSequence[Union[str, float, int]]HTupleHtuple (string / real / integer) (string / double / int / long) (HString / double / Hlong) (char* / double / Hlong)
通用参数的值。
默认值：
[]
建议值：
'true'"true""true""true""true""true", 'false'"false""false""false""false""false", 1, 0, 'om3'"om3""om3""om3""om3""om3", 'off'"off""off""off""off""off", 'ply'"ply""ply""ply""ply""ply", 'dxf'"dxf""dxf""dxf""dxf""dxf", 'obj'"obj""obj""obj""obj""obj", 'stl'"stl""stl""stl""stl""stl", 'stl_binary'"stl_binary""stl_binary""stl_binary""stl_binary""stl_binary", 'stl_ascii'"stl_ascii""stl_ascii""stl_ascii""stl_ascii""stl_ascii"
ObjectModel3DObjectModel3DObjectModel3DObjectModel3DobjectModel3Dobject_model_3d (输出控制) object_model_3d → HObjectModel3D, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)
3D 对象模型的句柄。
StatusStatusStatusStatusstatusstatus (输出控制) string(-array) → HTupleSequence[str]HTupleHtuple (string) (string) (HString) (char*)
Status information.
结果
算子 read_object_model_3dread_object_model_3dReadObjectModel3dReadObjectModel3dReadObjectModel3dread_object_model_3d 返回值 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.
可能的前趋
write_object_model_3dwrite_object_model_3dWriteObjectModel3dWriteObjectModel3dWriteObjectModel3dwrite_object_model_3d
可能的后继
affine_trans_object_model_3daffine_trans_object_model_3dAffineTransObjectModel3dAffineTransObjectModel3dAffineTransObjectModel3daffine_trans_object_model_3d,
object_model_3d_to_xyzobject_model_3d_to_xyzObjectModel3dToXyzObjectModel3dToXyzObjectModel3dToXyzobject_model_3d_to_xyz,
prepare_object_model_3dprepare_object_model_3dPrepareObjectModel3dPrepareObjectModel3dPrepareObjectModel3dprepare_object_model_3d
替代
xyz_to_object_model_3dxyz_to_object_model_3dXyzToObjectModel3dXyzToObjectModel3dXyzToObjectModel3dxyz_to_object_model_3d
另见
write_object_model_3dwrite_object_model_3dWriteObjectModel3dWriteObjectModel3dWriteObjectModel3dwrite_object_model_3d,
clear_object_model_3dclear_object_model_3dClearObjectModel3dClearObjectModel3dClearObjectModel3dclear_object_model_3d
模块
三维计量