Bei der Arbeit mit Dokumenten ist es häufiger notwendig, die Position von Elementen, wie zum Beispiel Textboxen und Signaturfeldern, zu definieren. Das dafür verwendete Koordinatensystem wird im Folgenden beschrieben.
PDF-Dokumente
Grundlage der Positionsbestimmung in PDF-Dokumenten ist der sogenannte PDF-Userspace. Innerhalb dieses Systems ist üblicherweise eine Cropbox definiert, die den sichtbaren Bereich des Dokuments festlegt. Ist die Cropbox einmal nicht definiert, wird stattdessen die Mediabox verwendet. Die Mediabox muss laut PDF-Standard immer definiert sein, und signotec-Komponenten können PDF-Dokumente ohne sie nicht verarbeiten.
Wird in der Dokumentation das “sichtbare Bezugssystem” oder “sichtbare Koordinaten” referenziert, ist immer das Koordinatensystem gemeint, dessen Ursprung in der oberen linken Ecke des sichtbaren Bereichs - definiert von der Cropbox, oder, wenn nicht vorhanden, der Mediabox - liegt, mit der X-Achse nach links und der Y-Achse nach unten.
Aus Gründen der Rückwärtskompatibilität ist auch ein zweites Bezugssystem (“zugrundeliegende Koordinaten”) verfügbar. Dieses hat die selbe Ausrichtung wie das sichtbare Koordinatensystem, aber seinen Ursprung am linken Rand des PDF-Userspaces und auf Höhe des oberen Rands der Mediabox. Es sollte nach Möglichkeit nicht mehr verwendet werden. Vor allem ist aber wichtig, dass durchgehend dasselbe Bezugssystem verwendet wird. Häufig sind Cropbox und Mediabox so definiert, dass die beiden Bezugssysteme identisch sind, wodurch Fehler durch die Verwendung von unterschiedlichen Bezugssystemen nur vereinzelt auftreten und nicht gleich auffallen.
Für die Positionierung von Elementen im Dokument wird jeweils ein Rechteck im Bezugssystem definiert. Das geschieht entweder über die Position der zwei gegenüberliegenden Eckpunkte links oben (“left”, “top”) und rechts unten (“right”, “bottom”), oder über den oberen linken Eckpunkt und die Breite und Höhe des Elements. Die X-Koordinate eines Punktes entspricht dabei immer dem Abstand zum linken Rand des verwendeten Bezugssystems, und die Y-Koordinate entspricht dem Abstand zum oberen Rand.
Die Koordinaten und Längen werden immer in der Einheit Points angegeben, soweit nicht explizit anders in der Dokumentation beschrieben.
Bilddokumente
In Bilddokumenten wird der gesamte Bildbereich als sichtbar interpretiert. Das Koordinatensystem, das zur Positionsbestimmung in Bilddokumenten verwendet wird, hat seinen Ursprung in der linken oberen Ecke, mit der X-Achse nach links und der Y-Achse nach unten. Bei der Arbeit mit Bilddokumenten haben den Methoden übergebene Optionsparameter, die das verwendete Koordinatensystem spezifizieren, keine Wirkung.
Für die Positionierung von Elementen im Dokument wird jeweils ein Rechteck im Bezugssystem definiert. Das geschieht entweder über die Position der zwei gegenüberliegenden Eckpunkte links oben (“left”, “top”) und rechts unten (“right”, “bottom”), oder über den oberen linken Eckpunkt und die Breite und Höhe des Elements. Die X-Koordinate eines Punktes entspricht dabei immer dem Abstand zum linken Rand des Bildes, und die Y-Koordinate entspricht dem Abstand zum oberen Rand.
Als Einheit für Koordinaten und Längen werden Pixel verwendet.