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. HALCON kann nur die ASCII-version des Formats lesen. 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 ignoriert und es werden
nur die bekannten Attribute eingelesen.
Stimmt der Name eines property-Eintrags in der 'ply'-Datei
mit dem Namen eines Standardattributs
überein (siehe set_object_model_3d_attrib), wird
der property-Eintrag
vorzugsweise in das Standardattribut eingelesen.
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), Punktnormalen ('vn'-Zeilen) und Polygonen ('f'-Zeilen), andere Daten werden ignoriert. Vorhandene Punktnormalen werden nur zurückgegeben, wenn es genau so viele Punktnormalen wie Punkte gibt. 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'.
'STEP-Dateiformat' (auch 'STP' oder 'Standard for the Exchange of Product Model Data'). Dies ist ein komplexes Dateiformat, das eine Vielzahl geometrischer Definitionen speichern kann und somit eine genaue Speicherung von 3D-Modellen ermöglicht. Aufgrund der limitierten Unterstützung der von STEP definierten Geometrien im HALCON 3D-Objektmodell wird eine Triangulierung dieser Geometrien durchgeführt, woraus Modelle bestehend aus Dreiecksoberflächen resultieren. Die Standard-Dateiendungen für dieses Format sind 'step' und 'stp'.
Mit diesem Format können verschiedene ASCII-Dateiformate, die 3D Information in Tabellenform enthalten, gelesen werden, beispielsweise 'ptx', 'pts', 'xyz' oder 'pcd'. Aktuell können nur punktgebundene Attribute gelesen werden, keine Dreiecke oder Polygone. Die Information eines 3D-Punktes wird in einer Zeile erwartet, gefolgt von der Information des nächsten 3D-Punktes in der nächsten Zeile. Das Dateiformat muss durch Setzen des generischen Parameters 'ascii_format' genauer beschrieben werden.
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'
und 'step' ignoriert. om3-Dateien werden immer unskaliert eingelesen.
Bei step-Dateien werden Einheiten direkt in den Dateien definiert, zusammen
mit den gespeicherten Daten gelesen und zur Skalierung auf die
HALCON-übliche Einheit 'm' verwendet.
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.
Werteliste: 'om3', 'dxf', 'off', 'ply', 'obj', 'stl', 'step', 'generic_ascii'.
Wandelt alle Flächen in Dreiecke um. Ist dieser Parameter auf 'true' gesetzt, so werden alle eingelesenen Polygone in Dreiecke konvertiert.
Gültig für Dateitypen: 'dxf', 'ply', 'off', 'obj'.
Werteliste: 'true', 'false'.
Default: 'false'.
Invertieren der Normalenrichtungen und Flächen. Ist dieser Parameter auf 'true' gesetzt, so wird die Ausrichtung aller Normalen und Flächen invertiert.
Gültig für Dateitypen: 'dxf', 'ply', 'off', 'obj', 'stl', 'step', 'generic_ascii'.
Werteliste: 'true', 'false'.
Default: 'false'.
DXF-spezifische Parameter (siehe unten).
Gültig für Dateitypen: 'dxf'
STEP-spezifischer Parameter.
Spezifiziert die maximal erlaubte Abweichung (in 'm') von der Modelloberfläche bei der Triangulierung. Ein kleinerer Wert generiert ein genaueres Modell, aber erhöht die Zeit zum Einlesen und die Anzahl an Punkten und Dreiecken in dem resultierenden Modell. Der Parameter kann auf 'auto' gesetzt werden, um ihn automatisch abhängig von der Modellgröße zu schätzen.
Gültig für Dateitypen: 'step'.
Wertevorschläge: 'auto', 0.0001, 0.00001.
Default: 'auto'.
Restriktion: 'max_surface_deviation' > 0
STEP-spezifischer Parameter.
STEP-Dateien können Definitionen von unabhängigen Modellkomponenten enthalten. Mit diesem Parameter kann jede Komponente als ein HALCON 3D-Objektmodell importiert werden. Wird der Parameter auf 0 gesetzt, wird die Datei als ein einziges Modell importiert. Bei 1 werden die Modellkomponenten grob voneinander getrennt, bei 2 werden die Modellkomponenten auf einer detaillierteren Ebene getrennt.
Gültig für Dateitypen: 'step'.
Werteliste: 0, 1, 2.
Default: 0.
generic_ascii-spezifischer Parameter.
Spezifiziert das Format der zu lesenden ASCII-Datei. Als Wert muss ein dict
übergeben werden, das Information zum Dateiinhalt enthält. Das dict definiert
die Information in den Spalten und Metainformation wie die Nummer der ersten
Zeile, die Punktinformation enthält. Beispiele sind am Ende der
Operatorreferenz oder im HDevelop Beispiel
read_object_model_3d_generic_ascii.hdev gegeben.
Die folgenden Parameter können als Schlüssel gesetzt werden:
Definiert die Attribute in den Spalten der Datei, gegeben als Tupel von
Strings. Alle punktbezogenen Standard- und erweiterten Attribute, die in
der Referenz von set_object_model_3d_attrib aufgeführt sind,
werden unterstützt. Mindestens 'point_coord_x',
'point_coord_y' und 'point_coord_z' müssen gesetzt
werden. Wenn Normalen verwendet werden sollen, müssen alle drei Komponenten
'point_normal_x', 'point_normal_y' und
'point_normal_z' gesetzt werden. Das Ignorieren von Spalten ist
möglich, indem '' an der entsprechenden Position im Tupel gesetzt
wird.
Wertevorschläge: ['point_coord_x', 'point_coord_y', 'point_coord_z'], ['point_normal_x', 'point_normal_y', 'point_normal_z'], 'red', 'green', 'blue', '&my_custom_attrib', ''.
Definiert das Trennzeichen zwischen den Spalten. Aktuell werden Leerzeichen, Tabs sowie Semikolons und Kommas unterstützt.
Werteliste: ' ', ';', ','.
Definiert die Nummer der ersten Zeile, die aus der Datei gelesen werden soll und kann beispielsweise genutzt werden, um Kopfzeilen zu überspringen. Die oberste Zeile der Datei entspricht 'first_point_line' 1.
Default: 1.
Restriktion: 'first_point_line' > 0
Definiert die Nummer der letzten Zeile, die aus der Datei gelesen werden soll und kann beispielsweise genutzt werden, um nicht unterstützte Information zu überspringen. Die oberste Zeile der Datei entspricht 'last_point_line' 1. Wenn 'last_point_line' auf -1 gesetzt wird, werden alle Zeilen gelesen.
Default: -1.
Restriktion: 'last_point_line' >= -1
Definiert den Start von Kommentaren in der zu lesenden Datei. Information hinter dem Kommentarstart wird beim Lesen der Datei übersprungen.
Wertevorschläge: '#', '*', '/', 'comment'.
Gültig für Dateityp: 'generic_ascii'.
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.
Gültig für Dateitypen: 'ply', 'off', 'obj'.
Default: -1.
Restriktion: 'xyz_map_width' > 0
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.
Gültig für Dateitypen: 'ply', 'off', 'obj'.
Default: -1.
Restriktion: 'xyz_map_height' > 0
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-Objektmodells 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.
Default: 'mvtec_bunny_normals'
Wertevorschläge: 'mvtec_bunny', 'glass_mug', 'bmc_mini', 'pipe_joint', 'clamp_sloped', 'tile_spacer', 'engine_part_bearing'
Dateiendung:
.off, .ply, .dxf, .om3, .obj, .stl, .step, .stp
Scale (input_control) number → (string / real / integer)
Skalierung der Daten in der Datei.
Default: '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.
Default: []
Werteliste: 'ascii_format', 'convert_to_triangles', 'file_type', 'invert_normals', 'max_approx_error', 'max_surface_deviation', 'min_num_points', 'split_level', 'xyz_map_height', 'xyz_map_width'
GenParamValue (input_control) string(-array) → (string / real / integer)
Werte der generischen Parameter.
Default: []
Wertevorschläge: 'true', 'false', 1, 0, 'auto', 'om3', 'off', 'ply', 'dxf', 'obj', 'stl', 'stl_binary', 'stl_ascii', 'step', 'generic_ascii'
ObjectModel3D (output_control) object_model_3d(-array) → (handle)
Handle des eingelesenen 3D-Objektmodells.
Status (output_control) string(-array) → (string)
Statusinformation.
* Example how to use file_type generic_ascii and generic parameter ascii_format to read the point attributes from a ply file.
FileFormat := dict{}
FileFormat.separator := ' '
FileFormat.columns := ['point_coord_x', 'point_coord_y', 'point_coord_z', 'point_normal_x', 'point_normal_y', 'point_normal_z']
FileFormat.first_point_line := 14
FileFormat.last_point_line := 2273
FileFormat.comment := 'comment'
read_object_model_3d ('glass_mug.ply', 'm', ['file_type', 'ascii_format'], ['generic_ascii', FileFormat], ObjectModel3D, Status)
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