EnvelopeGenerator/OPEN_TASK_SESSION_12.md

OPEN TASK - Session 12 (INCOMPLETE)

Task Description

Update coordinate system documentation in COPILOT_CONTEXT_EN.md and C# XML documentation files to reflect the correct unit (INCHES, not 1/100 inch).

Status

FAILED - PowerShell timeout, files not updated

---

What Was Discovered

1. Database Stores INCHES (Not DX Units)

Source: EnvelopeGenerator.Form/frmFieldEditor.vb (VB.NET legacy project)

Technology: GdPicture14.Annotations.AnnotationStickyNote

Code Evidence:

'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

Location: E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Form\frmFieldEditor.vb

2. Incorrect Documentation Found

File	Line	Wrong Claim	Correct Value
COPILOT_CONTEXT_EN.md	~43	"1/100 inch (DX units)"	INCHES
ReceiverUI/Models/AnnotationDto.cs	3-15	"Hundredths of an inch"	INCHES
Application/Common/Dto/AnnotationCreateDto.cs	29-69	"Hundredths of an inch (1/100 inch)"	INCHES

---

What Needs To Be Done

Task 1: Update COPILOT_CONTEXT_EN.md

File: E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\COPILOT_CONTEXT_EN.md

Action: Replace section ## AnnotationDto — Coordinate System (around line 43)

New Section Title: ## SignatureDto / AnnotationDto — Coordinate System

New Content Must Include:

1. Database storage format: INCHES, top-left origin
2. Source evidence: VB.NET code snippet from frmFieldEditor.vb
3. Conversion formulas:

   Inches → DevExpress (DX):  multiply by 100
   Inches → PDF Points:       multiply by 72
   Inches → PDF.js Canvas:    normalize to page size, then scale to pixels
   

4. Unit comparison table:

System	Unit	Origin	Conversion from INCHES
GdPicture14 (Source)	Inches	Top-left	Database format
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

Problem: Special characters (— and •) in file causing regex issues. Use exact string match or manual edit.

---

Task 2: Update C# XML Documentation

2.1 EnvelopeGenerator.ReceiverUI/Models/SignatureDto.cs

Location: E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.ReceiverUI\Models\SignatureDto.cs

Current State: Missing XML documentation

Action: Add XML docs to class and properties:

/// <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; }
}

---

2.2 EnvelopeGenerator.ReceiverUI/Models/AnnotationDto.cs

Location: E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.ReceiverUI\Models\AnnotationDto.cs

Lines to Change: 3-15 (XML doc comments)

Current (WRONG):

/// <b>Coordinate unit (X, Y):</b> Hundredths of an inch (1/100 inch ≈ 2.83 PDF points),

Correct:

/// <b>Coordinate unit (X, Y):</b> Inches (GdPicture14 native unit),

Full Updated XML Doc:

/// <summary>
/// Represents a pre-assigned signature annotation position on a specific page.
/// <br/><br/>
/// <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.
/// <br/><br/>
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
/// Convert: <c>xDX = xInches * 100.0</c>
/// <br/>
/// <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
{
    /// <summary>Unique identifier of the annotation.</summary>
    public long Id { get; init; }

    /// <summary>1-based page number within the document.</summary>
    public int Page { get; init; }

    /// <summary>Horizontal position in INCHES from the left edge of the page.</summary>
    public double X { get; init; }

    /// <summary>Vertical position in INCHES from the top edge of the page.</summary>
    public double Y { get; init; }
}

---

2.3 EnvelopeGenerator.Application/Common/Dto/AnnotationCreateDto.cs

Location: E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Application\Common\Dto\AnnotationCreateDto.cs

Lines to Change: 29-69 (XML doc for X and Y properties)

Current X Property (WRONG):

/// <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.
/// <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>
/// <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>
/// </summary>
public double? X { get; init; }

Correct X Property:

/// <summary>
/// Horizontal position of the signature field on the page.
/// <br/><br/>
/// <b>Unit:</b> INCHES (GdPicture14 native), origin at the <b>top-left</b> corner of the page, X increases to the right.
/// <br/>
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
/// Convert: <c>xDX = xInches * 100.0</c>
/// <br/>
/// <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; }

Current Y Property (WRONG):

/// <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.
/// <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>
/// <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>
/// </summary>
public double? Y { get; init; }

Correct Y Property:

/// <summary>
/// Vertical position of the signature field on the page.
/// <br/><br/>
/// <b>Unit:</b> INCHES (GdPicture14 native), origin at the <b>top-left</b> corner of the page, Y increases downward.
/// <br/>
/// <b>Conversion to DevExpress:</b> Multiply by 100 (DX uses 1/100 inch).
/// Convert: <c>yDX = yInches * 100.0</c>
/// <br/>
/// <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; }

---

Additional Context

Key Code Files

1. Source of Truth (VB.NET):

   • E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Form\frmFieldEditor.vb
   • E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Form\Controllers\FieldEditorController.vb

2. C# DTOs (Need Update):

   • E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.ReceiverUI\Models\SignatureDto.cs
   • E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.ReceiverUI\Models\AnnotationDto.cs
   • E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\EnvelopeGenerator.Application\Common\Dto\AnnotationCreateDto.cs

3. Documentation (Need Update):

   • E:\TekH\Visual Studio\EnvelopeGenerator_BlazorUIDev\COPILOT_CONTEXT_EN.md

Database Schema

Table: TBSIG_DOCUMENT_RECEIVER_ELEMENT

Columns:

• POSITION_X (FLOAT) — Stores INCHES
• POSITION_Y (FLOAT) — Stores INCHES
• WIDTH (FLOAT) — Stores INCHES
• HEIGHT (FLOAT) — Stores INCHES
• PAGE (INT) — 1-based page number

---

Unit Conversion Quick Reference

Database (GdPicture14):  Inches, top-left origin

→ DevExpress (LEGACY):   x_DX = x_inches * 100       (1/100 inch units)
                        y_DX = y_inches * 100

→ PDF Points (iText7):   x_pt = x_inches * 72        (bottom-left origin)
                        y_pt = (pageHeight_inches - y_inches - height_inches) * 72

→ PDF.js Canvas:         normalize to [0,1], then scale to pixels
                        x_normalized = x_inches / pageWidth_inches (e.g., 8.27 for A4)
                        y_normalized = y_inches / pageHeight_inches (e.g., 11.69 for A4)
                        x_pixel = x_normalized * canvasWidth * scale * dpr
                        y_pixel = y_normalized * canvasHeight * scale * dpr

→ PSPDFKit (Web):        x_pt = x_inches * 72        (top-left origin)
                        y_pt = y_inches * 72

A4 Page Dimensions:

• Width: 8.27 inches = 595 points = 827 DX units
• Height: 11.69 inches = 842 points = 1169 DX units

---

Notes for Next AI

1. DO NOT assume DevExpress units in database
2. DO NOT use PowerShell regex on UTF-8 files with special chars
3. USE replace_string_in_file tool with exact string match
4. VERIFY changes in all 4 files (1 markdown + 3 C# files)
5. TEST conversions with sample data (e.g., x=1.77, y=1.96)

---

Session 12 Changes Already Completed

1. ✅ Added SignatureService to DI (EnvelopeGenerator.ReceiverUI/Program.cs)

2. ✅ Fixed YARP routes for Blazor WASM static files (EnvelopeGenerator.API/yarp.json):

   • Added routes for appsettings.json, appsettings.Development.json
   • Added route for *.styles.css files
   • Added routes for /fonts/, /images/
   • Removed /wwwroot/ route (redundant)
   • Removed receiver-ui-annotation-fake route (no longer needed)

3. ✅ EnvelopeViewer.razor now successfully:

   • Loads PDF via DocumentService
   • Loads signatures via SignatureService
   • Displays PDF with PDF.js viewer
   • Console logs signature data (visible in browser F12)

---

End of Task Description