read_object_model_3d — Lesen eines 3D-Objektmodells aus einer Datei.
read_object_model_3d( : : FileName, Scale, GenParamName, GenParamValue : ObjectModel3D, Status)
read_object_model_3d liest ein 3D-Objektmodell aus der Datei
FileName und gibt das Handle des 3D-Objektmodells in
ObjectModel3D zurück.
Der Operator unterstützt die folgenden Dateiformate:
HALCON-Format für 3D-Objektmodelle. Dateien mit diesem Format
können mit write_object_model_3d geschrieben werden.
Die Standard-Dateiendung für dieses Format ist 'om3'.
AUTOCAD-Dateiformat. Weitere Details über dieses Format finden sich weiter unten. Die Standard-Dateiendung für dieses Format ist 'dxf'.
'Object File Format'. Dies ist ein einfaches ASCII-basiertes Format, welches 3D-Punkte und Polygone speichern kann. Das binäre OFF-Format wird nicht unterstützt. Die Standard-Dateiendung für dieses Format ist 'off'.
'Polygon File Format' (auch Stanford Triangle Format). Dies ist ein einfaches Dateiformat, welches 3D-Punkte, Punktnormalen, Polygone, Farbinformationen und punktbasierte benutzerdefinierte Attribute speichern kann. HALCON kann sowohl die ASCII- als auch die Binärversion des Formats lesen. Sollte die zu lesende Datei zusätzliche, nicht unterstützte Informationen beinhalten, so werden diese bei einem ASCII-File ignoriert und es werden nur die bekannten Attribute eingelesen. Beim Einlesen einer Binärdatei wird in diesem Fall ein Fehler zurückgegeben und kein Objektmodell erzeugt. Die Standard-Dateiendung für dieses Format ist 'ply'.
'OBJ file format' (auch 'Wavefront OBJ-Format'). Dies ist ein ASCII-basiertes Format, welches 3D-Punkte, Polygone, Normalen, Texturkoordinaten, Materialien und anderes speichern kann. HALCON unterstützt das Einlesen von Punkten ('v'-Zeilen) und Polygonen ('f'-Zeilen), andere Daten werden ignoriert. Die Standard-Dateiendung für dieses Format ist 'obj'.
'STL-Dateiformat' (auch 'Stereolithography', 'SurfaceTesselationLanguage', 'StandardTriangulationLanguage' oder 'StandardTesselationLanguage'). Dieses Dateiformat kann Dreiecke und Dreiecksnormalen speichern. Da das HALCON 3D-Objektmodell allerdings keine Dreiecksnormalen unterstützt, werden nur die Dreiecke eingelesen während die Dreiecksnormalen ignoriert werden. Die Normalen werden bei Bedarf aus den Dreiecken selbst berechnet. HALCON kann sowohl die ASCII- als auch die Binärversion des Formats lesen. Wird 'stl' angegeben so erkennt HALCON automatisch ob die Datei in der ASCII- oder der Binärversion des Formats vorliegt. Mit 'stl_ascii' bzw. 'stl_binary' kann explizit das ASCII- bzw. Binärformat gewählt werden. Die Standard-Dateiendung für dieses Format ist 'stl'.
Wird eine DXF-Datei eingelesen, so enthält der Ausgabeparameter
Status Informationen über die Anzahl der gelesenen 3D-Flächen
und, falls erforderlich, Hinweise auf Teile der DXF-Datei, die nicht gelesen
werden konnten.
Der Parameter Scale definiert die Dimension der in der Datei
auftretenden Koordinaten.
Wird der Parameter z.B. auf 'mm' gesetzt, so werden alle Einheiten
in 'mm' interpretiert und durch Multiplikation mit 0.001
in die HALCON-übliche Einheit 'm' umgewandelt.
Ein Wert von '100 mm' wird so zu '0.1 m'.
Alternativ zu einer Einheit kann für den Parameter auch direkt eine Zahl
angegeben werden, die mit allen Koordinatenwerten multipliziert wird.
Die Zuordnung von Einheiten zu Faktoren ergibt sich aus der folgenden
Tabelle:
| Einheit | Skalierungsfaktor |
|---|---|
| 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 |
Der Parameter Scale wird für Dateien vom Typ 'om3'
ignoriert, d.h. om3-Dateien werden immer unskaliert eingelesen.
Zum nachträglichen Skalieren eines 3D-Objektmodells kann
affine_trans_object_model_3d verwendet werden.
Eine Reihe weiterer optionaler Parameter kann gesetzt werden.
Die Namen und Werte dieser Parameter werden in GenParamName und
GenParamValue übergeben. Einige der Parameter gelten nicht für
alle Dateitypen. Die folgenden Werte sind für GenParamName
möglich:
Erzwingen eines Dateityps.
Wird dieser Parameter nicht gesetzt, so versucht
read_object_model_3d den Dateityp automatisch aus der
Dateiendung und dem Anfang der Datei zu erkennen.
Wird dieser Parameter gesetzt, so wird die Datei als Datei diesen Types
interpretiert.
Mögliche Werte: 'om3', 'dxf', 'off', 'ply', 'obj', 'stl'
Wandelt alle Flächen in Dreiecke um. Ist dieser Parameter auf 'true' gesetzt, so werden alle eingelesenen Polygone in Dreiecke konvertiert.
Mögliche Werte: 'true', 'false'
Standardwert: 'false'
Gültig für Dateitypen: 'dxf', 'ply', 'off', 'obj'
Invertieren der Normalenrichtungen und Flächen. Ist dieser Parameter auf 'true' gesetzt, so wird die Ausrichtung aller Normalen und Flächen invertiert.
Mögliche Werte: 'true', 'false'
Standardwert: 'false'
Gültig für Dateitypen: 'dxf', 'ply', 'off', 'obj', 'stl'
DXF-spezifische Parameter (siehe unten).
Gültig für Dateitypen: 'dxf'
Erstellt für das gelesene 3D-Objektmodell eine Abbildung welche jedem
der gelesenen 3D-Punkte eine Bildkoordinate zuweist, analog zu
xyz_to_object_model_3d.
Es wird angenommen, dass die 3D-Punkte in der Datei zeilenweise
vorliegen.
Der übergebene Wert wird als Breite des Bildes angenommen.
Die nötige Höhe des Bildes wird automatisch ermittelt.
Ist dieser Wert gesetzt, so kann das gelesene 3D-Objektmodell im Operator
object_model_3d_to_xyz mit der Methode 'from_xyz_map'
projiziert werden.
Nur einer der beiden Parameter 'xyz_map_width' und
'xyz_map_height' kann gesetzt werden.
Assertion: 'xyz_map_width' > 0 Standardwert: -1
Gültig für Dateitypen: 'ply', 'off', 'obj'
Analog zu 'xyz_map_width', jedoch wird angenommen dass die Punkte spaltenweise vorliegen. Die Breite des Bildes wird automatisch ermittelt. Nur einer der beiden Parameter 'xyz_map_width' und 'xyz_map_height' kann gesetzt werden.
Assertion: 'xyz_map_height' > 0 Standardwert: -1
Gültig für Dateitypen: 'ply', 'off', 'obj'
Falls ein 2D-Mapping vorhanden ist, wird seine Verwendung auf Grund
besserer Robustheit und höherer Verarbeitungsgeschwindigkeit empfohlen.
Vor allem für die Operatoren sample_object_model_3d und
surface_normals_object_model_3d,
sowie in der Vorbearbeitung eines 3D-Objekmodells für das
oberflächenbasierte 3D-Matching (Glättung, Entfernung der Ausreißer, und
Reduzieren der Domäne) ist daher die Verwendung des 2D-Mappings vorteilhaft.
Der Operator read_object_model_3d unterstützt die
folgenden DXF-Elemente:
POLYLINE
Vielflächennetz (Polyline flag 64)
3D Linienzüge (Polyline flag 8,9)
2D Linienzüge (Polyline flag 0)
LWPOLYLINE
2D Linienzüge (Polyline flag 0)
3DFACE
LINE
CIRCLE
ARC
SOLID
BLOCK
INSERT
Die zweidimensionalen linienhaften DXF-Elemente LINE, CICRLE und ARC werden nicht als Flächen interpretiert. Nur im Fall, dass sie extrudiert sind, werden die dadurch entstehenden Flächen in das 3D-Objektmodell eingefügt. Alle DXF-Elemente, die Linienzüge repräsentieren, werden als 3D Linien zum 3D-Objektmodell hinzugefügt.
Die gekrümmte Oberfläche extrudierter DXF-Elemente vom Typ CIRCLE und ARC wird durch ebene Flächen approximiert. Die Genauigkeit dieser Approximation kann über die beiden generischen Parameter 'min_num_points' und 'max_approx_error' gesteuert werden. Der Parameter 'min_num_points' legt fest, wie viele Stützpunkte mindestens für die Approximation des DXF-Elements CIRCLE bzw. ARC verwendet werden. Der Parameter 'min_num_points' bezieht sich immer auf den entsprechenden Vollkreis, auch für ARCs, d.h., wenn 'min_num_points' auf den Wert 50 gesetzt ist und ein DXF-Element vom Typ ARC eingelesen wird, das einen Halbkreis darstellt, so wird dieser durch mindestens 25 Stützpunkte approximiert. Der Parameter 'max_approx_error' legt fest, wie groß die maximale Abweichung der XLD-Kontur von dem idealen Kreis sein darf. Diese Abweichung wird in der Einheit bestimmt, die in der DXF-Datei verwendet wird. Für die Bestimmung der Genauigkeit der Approximation werden beide Kriterien ausgewertet und dasjenige verwendet, das zu einer genaueren Approximation führt.
Die intern verwendeten Defaultwerte für die generischen Parameter sind:
'min_num_points' = 20
'max_approx_error' = 0.25
Um eine genauere Approximation zu erreichen, muss entweder ein größerer Wert für 'min_num_points' oder ein kleinerer Wert für 'max_approx_error' verwendet werden.
Eine Möglichkeit, um eine passende DXF-Datei zu erzeugen, besteht darin, ein 3D-Modell des Objektes mit dem CAD-Programm AutoCAD zu erstellen. Dabei muss darauf geachtet werden, dass die Oberfläche des Objektes modelliert wird, nicht nur die Kanten. Linien, die z.B. Objektkanten darstellen, können von HALCON nicht verwendet werden, da sie nicht die Oberfläche des Objektes beschreiben. Wenn die Modellierung des Objektes abgeschlossen ist, kann das 3D-Modell im DWG-Format abgespeichert werden. Um die DWG-Datei in eine DXF-Datei zu konvertieren, die für die Verwendung in HALCON geeignet ist, sind die folgenden Schritte durchzuführen:
Exportieren des 3D CAD-Modells in eine 3DS-Datei mit dem AutoCAD-Befehl 3dsout. Dabei erfolgt eine Dreiecksvermaschung der Oberfläche des Objektes, d.h., die Oberfläche wird nur noch durch Dreiecke dargestellt. (Nutzer von AutoCAD 2007 oder neueren Versionen können sich ein Dienstprogramm, das diesen Befehl zur Verfügung stellt, auf den Internetseiten von Autodesk herunterladen.)
Öffnen einer neuen, leeren Zeichnung.
Importieren der 3DS-Datei in die neue Zeichnung mit dem AutoCAD-Befehl 3dsin.
Speichern des Modells in eine DXF R12-Datei.
Nutzer anderer CAD-Programme sollten sicherstellen, dass die Oberfläche des 3D-Modells vor dem Export nach DXF dreiecksvermascht wird. Wenn das CAD-Programm diese Funktionalität nicht zur Verfügung stellt, besteht oft die Möglichkeit, das 3D-Modell im proprietären Format des CAD-Programms abzuspeichern und anschließend mit einem Konverter für CAD-Formate, der die Dreiecksvermaschung durchführen kann, zu konvertieren.
Dieser Operator liefert ein Handle zurück. Es ist zu beachten, dass der Zustand einer Instanz dieses Handletyps durch bestimmte Operatoren geändert werden kann, obwohl das Handle als Eingabeparameter in diesen Operatoren verwendet wird.
FileName (input_control) filename.read → (string)
Dateiname der zu lesenden Datei.
Defaultwert: 'mvtec_bunny_normals'
Wertevorschläge: 'mvtec_bunny', 'glass_mug', 'bmc_mini', 'pipe_joint', 'clamp_sloped', 'tile_spacer'
Dateiendung: .off, .ply, .dxf, .om3, .obj, .stl
Scale (input_control) number → (string / real / integer)
Skalierung der Daten in der Datei.
Defaultwert: 'm'
Wertevorschläge: 'm', 'cm', 'mm', 'microns', 'um', 'nm', 'km', 'in', 'ft', 'yd', 1.0, 0.01, 0.001, 1.0e-6, 0.0254, 0.3048, 0.9144
GenParamName (input_control) string(-array) → (string)
Namen der generischen Parameter.
Defaultwert: []
Werteliste: 'convert_to_triangles', 'file_type', 'invert_normals', 'max_approx_error', 'min_num_points', 'xyz_map_height', 'xyz_map_width'
GenParamValue (input_control) string(-array) → (string / real / integer)
Werte der generischen Parameter.
Defaultwert: []
Wertevorschläge: 'true', 'false', 1, 0, 'om3', 'off', 'ply', 'dxf', 'obj', 'stl', 'stl_binary', 'stl_ascii'
ObjectModel3D (output_control) object_model_3d → (handle)
Handle des eingelesenen 3D-Objektmodells.
Status (output_control) string(-array) → (string)
Statusinformation.
read_object_model_3d liefert den Wert 2 (H_MSG_TRUE) wenn alle
Parameter korrekt sind und die Datei gelesen werden konnte.
Gegebenenfalls wird eine Fehlerbehandlung durchgeführt.
affine_trans_object_model_3d,
object_model_3d_to_xyz,
prepare_object_model_3d
write_object_model_3d,
clear_object_model_3d
3D Metrology