Formen

Die auf dieser Seite erklärten Attribute und Funktionen sind in der Kategorie Shapes zu finden.

Ein häufiger Anwendungsfall ist die Auswahl bestimmter Bildbereiche durch den Benutzer. Dies kann eine Region of Interest oder die Position eines Objekts sein. Ein anderer verwandter Anwendungsfall ist die benutzerdefinierte Messung von Entfernungen oder Bereichen innerhalb eines Bildes.

Um all diesen Anwendungsfällen Rechnung zu tragen, bieten die Eigenschaften in der Kategorie Shapes eine flexible Funktionalität zum Zeichnen und Bearbeiten verschiedener Formen auf dem Bild und zum Abrufen ihrer jeweiligen geometrischen Beschreibungen.

Eigenschaft: ShapeSelectionActive

Die Auswahl einer Form kann über die Eigenschaft ShapeSelectionActive bzw. über den Shape-Button in der Toolbar aktiviert werden. Solange diese Eigenschaft aktiv ist, kann die Form durch Klicken auf die Bildoberfläche gezeichnet und durch Ziehen und Ablegen der Eckpunkte oder der Form selbst bearbeitet werden. Wenn diese Eigenschaft auf false gesetzt wird und die Eigenschaft ShapeAutoClear aktiv ist, wird die aktuelle Form zurückgesetzt und geht verloren; eventuell benötigte Daten müssen also vorher extrahiert werden.

Die geometrische Beschreibung der gezeichneten Form kann über die Eigenschaft ShapeData abgerufen werden. Je nach der Eigenschaft ShapeType (siehe unten) haben die Formdaten ein anderes Format. Sie können genau das gleiche Format erwarten, das in den interaktiven Controls selbst verwendet wird (z. B. TcHmiVnPolygon und TcHmiVnRectangle), da das Symbol direkt an das intern verwendete Shape Control gebunden ist. Mit der Eigenschaft ShapeLimitToImage kann die Form auf den Bildbereich beschränkt werden. Wenn dies nicht der Fall ist (default), ist zu beachten, dass die Formen auch negative Werte annehmen können. Dies kann mit der Funktion shapeIsInImageArea abgefragt werden.

Eigenschaften: ShapeType und ShapeData

Es stehen verschiedene Arten von Shapes zur Verfügung, die auf zwei verschiedenen Datentypen basieren. Sie können über die Eigenschaft ShapeType eine der folgenden Formen auswählen:

ShapeType	ShapeData	PLC Declaration
Point	[[x, y]]	`ARRAY[0..0] OF TcVnPoint2_REAL or ARRAY[0..0] OF TcVnPoint2_LREAL`
Line	[[x1, y1], [x2, y2]]	`ARRAY[0..1] OF TcVnPoint2_REAL or ARRAY[0..1] OF TcVnPoint2_LREAL`
Square, Rectangle, Circle, Ellipse	{ fAngle: angle, aCenter: [cx, cy], stSize: { fWidth: width, fHeight: height, }, }	`TcVnRotatedRectangle`
Polygon	[[x1, y1], [x2, y2], …, …, [xn, yn]]	`ARRAY[0..n] OF TcVnPoint2_REAL or ARRAY[0..n] OF TcVnPoint2_LREAL`

Die Werte in ShapeData beziehen sich auf die Bildkoordinaten des Original-Bilds.

	Da die Shape-Typen Quadrat und Kreis per Definition immer die gleiche Höhe und Breite haben, werden sie beim Anklicken der zweiten Position nicht genau an diesen Endpunkt gezeichnet, wenn das Seitenverhältnis nicht gleich ist. In diesem Fall kann die gewünschte Position durch Verschieben der entsprechenden Ecke erreicht werden.

Um die Daten der Shape-Typen Quadrat und Rechteck vom Typ TcVnRotatedRectangle direkt an eine SPS-Variable vom Typ TcVnRectangle_UDINT oder ein TcVnRectangle übergeben und als aufrechtes Begrenzungsrechteck ohne Drehwinkel verwenden zu können, steht die Konvertierungsfunktion ToUprightRectangle zur Verfügung. Für den umgekehrten Fall gibt es die ToRotatedRectangle Funktion.

Programmatisch kann die ShapeData-Eigenschaft per Java Skript wie folgt verändert werden:

let control = TcHmi.Controls.get("TcHmiVnImage")
// Polygon with 4 Points
control.setShapeData([[10, 10], [10, 100], [150, 150], [100, 10]])

// Rectangle
control.setShapeData({"aCenter":[200,200],"fAngle":15,"stSize":{"fWidth":150,"fHeight":150}})

Im ersten Beispiel wird ein Polygon mit einem Array von 4 Punkten geschrieben. Zum Schreiben eines Punkts benötigt man nur das erste Element und für eine Linie die ersten beiden. Im zweiten Beispiel wird ein Rechteck geschrieben. Da die Shape Typen Quadrat, Kreis und Ellipse auf dem gleichen Datentyp basieren, kann die gleiche Schreibweise auch für diese Typen verwendet werden.

Die Daten können auch per WriteToSymbol-Aktion an ShapeData geschrieben werden. Dazu kopieren Sie den Teil innerhalb der runden Klammern der setShapeData() Funktion und fügen ihn als Objektwert ein.

Eigenschaft: `ShapeAutoClear`

Wenn die Eigenschaft ShapeAutoClear aktiv ist und der ShapeType geändert wird, während ShapeSelectionActive true ist, wird die aktuelle Form zurückgesetzt und eine neue Form des ausgewählten Formtyps kann gezeichnet werden. Wenn ShapeAutoClear nicht aktiv ist und zwischen Formtypen des gleichen Basis-Controls umgeschaltet wird, bleiben die Daten beim Umschalten des ShapeType erhalten und es wird direkt die neue Form angezeigt. Die Typen Punkt, Linie und Polygon gehören dabei zu einer Gruppe die das gleiche Basis-Control verwenden, die Typen Quadrat, Rechteck, Kreis und Ellipse zu der anderen.

Erscheinungsbild

Das Aussehen der Form und der Bedienpunkte kann durch Einstellen der Farbe und der Größe/Dicke der Kontur geändert werden:

Mit ShapeStrokeThickness kann die Dicke der Linien in Pixeln eingestellt werden.
Mit ShapeHandleSize kann die Größe der angezeigten Bedienpunkte der Form in Pixeln eingestellt werden
Mit ShapeClickableSize kann die Größe der klickbaren Fläche eines Bedienpunkts in Pixeln eingestellt werden. Das kann die Bedienung auf Touch-Panels vereinfachen, ohne die Handles unnötig groß anzeigen zu müssen.
Über ShapeStrokeColor und ShapeHandleColor kann die Farbe der Linien und die der Bedienpunkte unabhängig voneinander eingestellt werden.

Eigenschaft: `ShapeIsRotatable`

Wenn ShapeIsRotatable aktiv ist, wird bei geeigneten Formen (Linie, Rechteck, Quadrat, Ellipse, Polygon) ein zusätzliches Handle angezeigt, mit dem die Form rotiert werden kann. Über die ShapeAngleInterval Eigenschaft kann die Schrittgröße, in der die Rotation der Form geändert werden kann, in Grad eingestellt werden. Bei dem Defaultwert 0° kann die Form beliebig gedreht werden. Wenn die Form z. B. nur in 4 Positionen platziert werden darf, würde man 90° als Wert eintragen.

Eigenschaft: ShapeLimitToImage und ShapeIsInImageArea

Häufig ist es erforderlich, dass eine Form vollständig innerhalb des Bildes liegt, z. B.,um eine Region of Interest setzen zu können. Wenn die Eigenschaft ShapeLimitToImage aktiv ist, kann eine Form nur innerhalb des Bildes gezeichnet und bewegt werden. Diese Einschränkung wirkt sich nicht auf das programmatische Setzen einer Form aus, sondern lediglich auf grafische Interaktionen. Weiterhin ist zu beachten, dass wenn ShapeIsRotatable und ShapeAngleInterval gesetzt sind, die Form weiterhin uneingeschränkt gedreht werden kann.

Wenn ShapeLimitToImage nicht aktiv ist, kann die Positionierung der Form über die Eigenschaft ShapeIsInImageArea abgefragt werden. Diese gibt nur dann true zurück, wenn aktuell valide ShapeData vorliegen und wenn alle Eckpunkte der Form innerhalb des Bildbereichs liegen. Bei den Formen Circle und Ellipse werden ebenfalls die Eckpunkte zur Überprüfung verwendet. Um zwischen einem nicht vorhandenen und einem nicht im Bild liegenden Shape unterscheiden zu können, sollte zusätzlich auf ShapeSelectionActive und valide ShapeData abgefragt werden.

Eigenschaft: `ShapeDataUpdate`

Wann eine Aktualisierung der Eigenschaft ShapeData erfolgen soll, kann über die Eigenschaft ShapeDataUpdate festgelegt werden. Wenn onChanged ausgewählt ist, wird ShapeData während einer grafischen Interaktion fortwährend aktualisiert. Wenn hingegen onConfirmed ausgewählt ist, wird ShapeData erst am Ende einer Interaktion aktualisiert.

Eigenschaften: ShapePolygonNumPoints und ShapePolygonClosed

Wenn die Eigenschaft ShapeType auf Polygon eingestellt ist, kann die Anzahl an Punkten ab wann ein Polygon als abgeschlossen betrachtet wird, über die Eigenschaft ShapePolygonNumPoints festgelegt werden. Wenn beispielsweise drei Punkte angegeben werden, wird das Polygon beim Zeichnen des dritten Punkts automatisch vervollständigt. Wenn der Defaultwert 0 verwendet wird, ist die Anzahl an Punkten beliebig. Das Polygon wird dann erst beim Klick auf den ersten Punkt vervollständigt. Mit der Eigenschaft ShapePolygonClosed kann zudem festgelegt werden, ob der erste und der letzte Punkt des Polygons verbunden werden sollen, also ob das Polygon geschlossen angezeigt wird oder nicht.

Methode: `clearShape()`

Die gezeichnete Form kann programmatisch durch Aufruf der Methode clearShape gelöscht werden.

Anzeigeelement

Um den Anwendungsfall der Messung von Entfernungen oder Flächen innerhalb des Bildes zu bedienen, bietet die Infobar ein Element zur Anzeige von Text, der die aktuell gezeichnete Form repräsentiert. Standardmäßig wird für den Formtyp "Punkt" die Koordinate, für "Linie" die Linienlänge, für "Polygon" die Anzahl der Punkte und für die Formtypen "Quadrat ", "Rechteck", "Kreis" und "Ellipse" die Fläche angezeigt. Sollen weitere oder andere Informationen angezeigt werden, kann dies mithilfe einer eigenen ShapeValueFormatting Funktion realisiert werden.

Abfrage der Formtypen und Datenwerte

Abhängig vom ausgewählten Formtyp können die Daten in ShapeData verschiedene Formate haben. Um festzustellen welches Format vorliegt, kann entweder der aktuelle ShapeType abgefragt oder anhand der Datenwerte ermittelt werden, z. B. ob die Eigenschaft fAngle definiert ist. Wenn das der Fall ist, liegt ein TcVnRotatedRectangle Typ vor, ansonsten ein Array von Punkten. Um abzufragen, wie viele Punkte im Array enthalten sind, kann die Länge abgefragt werden. Über die Anzahl kann dann festgestellt werden, ob ein Punkt, eine Linie oder ein Polygon mit welcher Anzahl von Punkten vorliegt.

Weiterhin kann durch Abfrage der einzelnen Werte geprüft werden, ob valide Daten vorliegen. Beim Löschen oder Zurücksetzen der Formdaten werden die einzelnen Werte mit 0 beschrieben, was einen ungültigen Wert darstellt.

Über diese Abfragen kann sichergestellt werden, dass die verschiedenen Formtypen jeweils an eine dafür vorgesehene SPS-Variable vom gleichen Typ geschrieben werden und dass nur gültige Daten in das Steuerungsprogramm übernommen werden können.

Events: onShapeChanged und onShapeConfirmed

Um über eine Änderung der Form informiert zu werden, stehen die beiden Events onShapeChanged und onShapeConfirmed zur Verfügung.

Das Event onShapeChanged wird ausgelöst, sobald sich ShapeData ändert. Zu einer Änderung kann es beim programmatischen Setzen von ShapeData, beim Aufruf der Methode clearShape() und während grafischer Interaktionen kommen. Dieses Event ist dazu da, die Änderung von ShapeData live zu verfolgen, vorausgesetzt, dass ShapeDataUpdate auf den Wert onChanged gesetzt ist.

Das Event onShapeConfirmed wird ausgelöst, wenn das Shape programmatisch gesetzt oder nachdem eine grafische Interaktion mit dem Shape abgeschlossen wurde. Dieses Event wird unter der Voraussetzung ausgelöst, dass ShapeData valide ist.

Erweiterte Nutzung von Shapes

Die Shape-Funktionalität wird über separate Controls implementiert, die in das Image Watch Control eingebunden sind. Diese Shape-Controls besitzen einige Properties, die nicht direkt über das ImageWatch Control verfügbar sind. Dazu zählt z. B. das exakte Seitenverhältnis eines Rechtecks. Auf diese Properties kann entweder programmatisch oder durch separate Verwendung der Shape-Controls zugegriffen werden.