Standardize coordinate system to use INCHES
Updated the digital document signing system to use INCHES as the standard unit for annotations and signatures, aligning with GdPicture14's native format. Previously used DevExpress units (1/100 inch) and other formats have been replaced.
- Updated `AnnotationDto` to reflect the new coordinate system.
- Introduced `SignatureDto` for signature positions, deprecating `AnnotationDto`.
- Added conversion formulas for transforming coordinates between INCHES and other systems (DevExpress, PDF Points, PDF.js, etc.).
- Added a unit comparison table and A4 page dimensions in various units.
- Introduced a new read-only PDF.js viewer for envelopes (`/envelope/{EnvelopeKey}`).
These changes improve consistency, simplify conversions, and align with modern tools like PSPDFKit and iText7.
This commit is contained in:
@@ -40,22 +40,60 @@ A digital document signing system. Senders upload PDFs and place signature annot
|
||||
|
||||
---
|
||||
|
||||
## AnnotationDto — Coordinate System
|
||||
## SignatureDto / AnnotationDto — Coordinate System
|
||||
|
||||
**Database Storage Format:** INCHES (GdPicture14 native unit)
|
||||
**Origin:** Top-left corner of page
|
||||
**Axes:** X increases rightward, Y increases downward
|
||||
|
||||
### Source Evidence (VB.NET Legacy Code)
|
||||
|
||||
```vb
|
||||
' From: EnvelopeGenerator.Form/frmFieldEditor.vb
|
||||
' GdPicture14.Annotations.AnnotationStickyNote
|
||||
|
||||
'Breite und Höhe in Inches (4,5*5cm)
|
||||
Private Const SIGNATURE_WIDTH As Single = 1.77 ' 1.77 inches = 4.5cm
|
||||
Private Const SIGNATURE_HEIGHT As Single = 1.96 ' 1.96 inches = 5cm
|
||||
|
||||
Sub LoadAnnotation(pElement As Signature, ...)
|
||||
oAnnotation.Left = CSng(pElement.X) ' Direct assignment ? INCHES
|
||||
oAnnotation.Top = CSng(pElement.Y)
|
||||
oAnnotation.Width = CSng(pElement.Width)
|
||||
oAnnotation.Height = CSng(pElement.Height)
|
||||
End Sub
|
||||
```
|
||||
|
||||
### Conversion Formulas
|
||||
|
||||
```
|
||||
Unit : 1/100 inch (DX units) — DevExpress XtraReports native
|
||||
Origin : Top-left corner of page
|
||||
X : increases rightward
|
||||
Y : increases downward
|
||||
Inches ? DevExpress (DX): x_DX = x_inches * 100.0
|
||||
y_DX = y_inches * 100.0
|
||||
|
||||
A4 in DX units: Width = 827, Height = 1169
|
||||
Inches ? PDF Points: x_pt = x_inches * 72.0
|
||||
y_pt = x_inches * 72.0
|
||||
|
||||
Conversions:
|
||||
PSPDFKit (pt, top-left): xDX = xPsPdf * (100/72)
|
||||
GDPicture (pt, bottom-left): yDX = (pageHeightPt - yGD - elemHeightPt) * (100/72)
|
||||
DX ? PDF points: pt = dx * (72/100)
|
||||
Inches ? PDF.js Canvas: normalize to [0,1], then scale to pixels
|
||||
x_norm = x_inches / pageWidth_inches
|
||||
y_norm = y_inches / pageHeight_inches
|
||||
x_px = x_norm * canvasWidth * scale * dpr
|
||||
y_px = y_norm * canvasHeight * scale * dpr
|
||||
```
|
||||
|
||||
### Unit Comparison Table
|
||||
|
||||
| System | Unit | Origin | Conversion from INCHES |
|
||||
|--------|------|--------|------------------------|
|
||||
| **GdPicture14** (Source) | **Inches** | Top-left | Database format (no conversion) |
|
||||
| DevExpress (LEGACY) | 1/100 inch (DX) | Top-left | `x_DX = x_inches * 100` |
|
||||
| PDF.js (NEW) | Pixels | Top-left | `normalize ? scale` |
|
||||
| PDF Points (iText7) | Points (1/72") | **Bottom-left** | `x_pt = x_inches * 72` + Y-flip |
|
||||
| PSPDFKit (Web) | Points (1/72") | Top-left | `x_pt = x_inches * 72` |
|
||||
|
||||
**A4 Page Dimensions:**
|
||||
- Width: 8.27 inches = 595 points = 827 DX units
|
||||
- Height: 11.69 inches = 842 points = 1169 DX units
|
||||
|
||||
---
|
||||
|
||||
## EnvelopeViewer (NEW) — PDF.js Read-Only Viewer
|
||||
|
||||
@@ -37,26 +37,29 @@ public record AnnotationCreateDto
|
||||
/// <summary>
|
||||
/// Horizontal position of the signature field on the page.
|
||||
/// <br/><br/>
|
||||
/// <b>DevExpress unit:</b> Hundredths of an inch (1/100 inch ≈ 2.83 PDF points), origin at the <b>top-left</b> corner of the page, X increases to the right.
|
||||
/// <b>Unit:</b> INCHES (GdPicture14 native), origin at the <b>top-left</b> corner of the page, X increases to the right.
|
||||
/// <br/>
|
||||
/// <b>Difference from PSPDFKit:</b> PSPDFKit also uses top-left origin but measures in PDF points (1/72 inch).
|
||||
/// To convert: <c>xDevExpress = xPsPdfKit * (100.0 / 72.0)</c>
|
||||
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
|
||||
/// Convert: <c>xDX = xInches * 100.0</c>
|
||||
/// <br/>
|
||||
/// <b>Difference from GDPicture:</b> GDPicture uses PDF points with <b>bottom-left</b> origin (standard PDF coordinate system).
|
||||
/// The X axis is the same direction, only unit conversion is needed: <c>xDevExpress = xGdPicture * (100.0 / 72.0)</c>
|
||||
/// <b>Conversion to PDF Points:</b> Multiply by 72 (PSPDFKit, iText7 use 1/72 inch).
|
||||
/// Convert: <c>xPt = xInches * 72.0</c>
|
||||
/// </summary>
|
||||
public double? X { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Vertical position of the signature field on the page.
|
||||
/// <br/><br/>
|
||||
/// <b>DevExpress unit:</b> Hundredths of an inch (1/100 inch ≈ 2.83 PDF points), origin at the <b>top-left</b> corner of the page, Y increases downward.
|
||||
/// <b>Unit:</b> INCHES (GdPicture14 native), origin at the <b>top-left</b> corner of the page, Y increases downward.
|
||||
/// <br/>
|
||||
/// <b>Difference from PSPDFKit:</b> PSPDFKit also uses top-left origin and Y increases downward, but measures in PDF points (1/72 inch).
|
||||
/// To convert: <c>yDevExpress = yPsPdfKit * (100.0 / 72.0)</c>
|
||||
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
|
||||
/// Convert: <c>yDX = yInches * 100.0</c>
|
||||
/// <br/>
|
||||
/// <b>Difference from GDPicture:</b> GDPicture uses PDF points with <b>bottom-left</b> origin, so Y increases <b>upward</b> (PDF standard).
|
||||
/// To convert: <c>yDevExpress = (pageHeightInPt - yGdPicture - elementHeightInPt) * (100.0 / 72.0)</c>
|
||||
/// <b>Conversion to PDF Points (top-left origin):</b> Multiply by 72.
|
||||
/// Convert: <c>yPt = yInches * 72.0</c>
|
||||
/// <br/>
|
||||
/// <b>Conversion to PDF Points (bottom-left origin - iText7):</b> Y-flip required.
|
||||
/// Convert: <c>yPt = (pageHeightInches - yInches - elemHeightInches) * 72.0</c>
|
||||
/// </summary>
|
||||
public double? Y { get; init; }
|
||||
|
||||
|
||||
@@ -3,15 +3,17 @@ namespace EnvelopeGenerator.ReceiverUI.Models;
|
||||
/// <summary>
|
||||
/// Represents a pre-assigned signature annotation position on a specific page.
|
||||
/// <br/><br/>
|
||||
/// <b>Coordinate unit (X, Y):</b> Hundredths of an inch (1/100 inch ? 2.83 PDF points),
|
||||
/// <b>Coordinate unit (X, Y):</b> Inches (GdPicture14 native unit),
|
||||
/// origin at the <b>top-left</b> corner of the page, both axes increase downward/rightward.
|
||||
/// This matches the DevExpress XtraReports coordinate system (<see cref="System.Drawing.RectangleF"/>).
|
||||
/// <br/><br/>
|
||||
/// <b>Difference from PSPDFKit:</b> Same origin (top-left) and direction, but PSPDFKit uses PDF points (1/72 inch).
|
||||
/// Convert: <c>xDX = xPsPdf * (100.0 / 72.0)</c>
|
||||
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
|
||||
/// Convert: <c>xDX = xInches * 100.0</c>
|
||||
/// <br/>
|
||||
/// <b>Difference from GDPicture:</b> GDPicture uses PDF points with <b>bottom-left</b> origin (PDF standard); Y is flipped.
|
||||
/// Convert: <c>yDX = (pageHeightPt - yGD - elemHeightPt) * (100.0 / 72.0)</c>
|
||||
/// <b>Conversion to PDF Points:</b> Multiply by 72 (1 inch = 72 points).
|
||||
/// Convert: <c>xPt = xInches * 72.0</c>
|
||||
/// <br/>
|
||||
/// <b>Y-axis for PDF (bottom-left origin):</b> Flip required for iText7.
|
||||
/// Convert: <c>yPt = (pageHeightInches - yInches - elemHeightInches) * 72.0</c>
|
||||
/// </summary>
|
||||
[Obsolete("Use SignatureDto with SignatureService.")]
|
||||
public record AnnotationDto
|
||||
@@ -22,9 +24,9 @@ public record AnnotationDto
|
||||
/// <summary>1-based page number within the document.</summary>
|
||||
public int Page { get; init; }
|
||||
|
||||
/// <summary>Horizontal position in hundredths of an inch from the left edge of the page.</summary>
|
||||
/// <summary>Horizontal position in INCHES from the left edge of the page.</summary>
|
||||
public double X { get; init; }
|
||||
|
||||
/// <summary>Vertical position in hundredths of an inch from the top edge of the page.</summary>
|
||||
/// <summary>Vertical position in INCHES from the top edge of the page.</summary>
|
||||
public double Y { get; init; }
|
||||
}
|
||||
|
||||
@@ -1,13 +1,22 @@
|
||||
namespace EnvelopeGenerator.ReceiverUI.Models;
|
||||
|
||||
/// <summary>
|
||||
/// Represents a signature position on a PDF page.
|
||||
/// Coordinates stored in INCHES (GdPicture14 native unit).
|
||||
/// Origin: Top-left corner, X increases right, Y increases down.
|
||||
/// </summary>
|
||||
public class SignatureDto
|
||||
{
|
||||
/// <summary>Unique identifier.</summary>
|
||||
public int Id { get; set; }
|
||||
|
||||
/// <summary>Horizontal position in INCHES from left edge.</summary>
|
||||
public double X { get; set; }
|
||||
|
||||
/// <summary>Vertical position in INCHES from top edge.</summary>
|
||||
public double Y { get; set; }
|
||||
|
||||
/// <summary>1-based page number.</summary>
|
||||
public int Page { get; set; }
|
||||
|
||||
}
|
||||
Reference in New Issue
Block a user