Biến đổi không gian tọa độ: xoay, co giãn, xô nghiêng và lật gương

Tổng quan nhanh

Phép biến đổi không gian tọa độ biến đổi phần vẽ quanh một điểm trục mà bạn chọn. Công thức này trình bày xoay, co giãn, xô nghiêng và lật gương. Mỗi phép biến đổi được cô lập trong một khối lưu trạng thái đồ họa, nên không ảnh hưởng đến nội dung phía sau. Công thức dựa trên examples/21-transforms.php.

Cài đặt

composer require nextpdf/core:^3

Bạn không cần gói Pro hoặc Enterprise. Giao diện lập trình ứng dụng (API) dành cho phép biến đổi đi kèm với Core và hoạt động trên PHP 8.1 đến 8.4.

Tổng quan khái niệm

Nội dung trong Portable Document Format (PDF) được vẽ trong không gian người dùng. Theo mặc định, không gian người dùng có gốc tọa độ ở góc dưới bên trái của trang và một đơn vị bằng 1/72 inch (ISO 32000-2 §8.3.2). Một phép biến đổi nhân ma trận biến đổi hiện tại (CTM) với một ma trận mới bằng toán tử cm (§8.3.4). Các phép biến đổi được kết hợp bằng cách nối ma trận, nên thứ tự rất quan trọng.

NextPDF cho phép bạn làm việc trong hệ tọa độ tác giả có gốc ở góc trên bên trái. Ở bên trong, nó chuyển đổi hệ đó sang không gian người dùng có gốc ở góc dưới bên trái thông qua phép chiếu toY() trong các phương thức biến đổi. Vị trí dùng đơn vị của không gian người dùng: điểm PDF, trong đó 1 pt bằng 1/72 in. Để giữ một phép biến đổi cục bộ, hãy bọc nó giữa startTransform() và stopTransform(). Các phương thức này phát ra toán tử trạng thái đồ họa q (lưu) và Q (khôi phục) (§8.4.2). Mọi nội dung được vẽ giữa chúng đều kế thừa phép biến đổi. Mọi nội dung sau stopTransform() trở về CTM trước đó. Mỗi lệnh gọi rotate()/scale()/skewX()/mirrorH() nhận một điểm trục tường minh, nên phép biến đổi được neo đúng nơi bạn mong đợi thay vì ở gốc tọa độ của trang.

Bề mặt API

Bề mặt API được tạo từ PHPDoc. Các điểm vào chính nằm trong trait \NextPDF\Core\Concerns\HasTransforms:

Document::startTransform(): static — phát ra q và mở một khối trạng thái đồ họa
Document::stopTransform(): static — phát ra Q và đóng khối đó
Document::rotate(float $angle, float $x = 0, float $y = 0): static
Document::scale(float $sx, float $sy, float $x = 0, float $y = 0): static
Document::skewX(float $angle, float $x = 0, float $y = 0): static / skewY(...)
Document::mirrorH(float $x = 0): static / mirrorV(float $y = 0): static
Document::translateCtm(float $dx, float $dy): static

Mẫu mã — Bắt đầu nhanh

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Coordinate Transforms');
$doc->addPage();

$cx = 60.0;
$cy = 60.0;

// Rotate 30° around (cx, cy). The transform is scoped to this block.
$doc->startTransform();
$doc->rotate(30, $cx, $cy);
$doc->setFont('helvetica', '', 14);
$doc->text($cx, $cy, 'Rotated 30 degrees');
$doc->stopTransform();

// Back to the untransformed CTM — this text is upright.
$doc->setFont('helvetica', '', 10);
$doc->text($cx, $cy + 20, 'Not rotated');

$doc->save(__DIR__ . '/transforms.pdf');

echo "Created: transforms.pdf\n";

Mẫu mã — Bản chính thức

Chương trình độc lập này chạy trong khung cookbook. Nó tái hiện phần co giãn của examples/21-transforms.php. Mỗi phép biến đổi nằm trong một khối lưu trạng thái đồ họa với một điểm trục tường minh. Trạng thái màu và đường nét được đặt lại ở cuối, nên không có gì rò rỉ sang phần sau của trang.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Coordinate Transforms');
$doc->addPage();

$doc->setFont('helvetica', 'B', 13);
$doc->cell(0, 8, 'Scaling a reference square at 0.5x, 1.0x, 1.5x, 2.0x', newLine: true);
$doc->ln(6);

$scaleBaseY   = $doc->getY();
$scaleFactors = [0.5, 1.0, 1.5, 2.0];

$doc->setDrawColor(30, 58, 138);
$doc->setLineWidth(0.4);

foreach ($scaleFactors as $idx => $factor) {
    $cx = 25.0 + $idx * 45;
    $cy = $scaleBaseY + 5;

    $doc->startTransform();
    $doc->scale($factor, $factor, $cx, $cy);   // scale about (cx, cy)

    $doc->setFillColor(220, 230, 241);
    $doc->rect($cx, $cy, 15, 15, 'DF');
    $doc->line($cx, $cy, $cx + 15, $cy + 15);

    $doc->stopTransform();                      // CTM restored here

    // Drawn AFTER the block — at the original scale, untransformed.
    $doc->setFont('helvetica', '', 8);
    $doc->setTextColor(0);
    $doc->text($cx, $scaleBaseY + 38, sprintf('%.1fx', $factor));
}

// Explicit state reset so nothing carries into the next section.
$doc->setTextColor(0);
$doc->setFillColor(255);
$doc->setDrawColor(0);

// The harness sets NEXTPDF_COOKBOOK_OUTPUT and runs this script twice under
// the structural profile (the transform stream itself is deterministic).
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false && $out !== '' ? $out : __DIR__ . '/transforms.pdf');

echo "Wrote transforms.pdf\n";

STDOUT dự kiến:

Wrote transforms.pdf

Ví dụ đầy đủ bao gồm cả bốn họ phép biến đổi: xoay, co giãn, xô nghiêng và lật gương. Chạy bằng php examples/21-transforms.php; lệnh này ghi ra examples/output/21-transforms.pdf.

Trường hợp biên & điểm cần lưu ý

Luôn ghép cặp khối. Mỗi startTransform() phải có một stopTransform() tương ứng. Số lượng q/Q không cân bằng sẽ làm hỏng trạng thái đồ họa cho phần còn lại của trang (ISO 32000-2 §8.4.2). NextPDF theo dõi độ sâu, nhưng ở cấp độ công thức, quy ước vẫn là một-đối-một.
Thứ tự không giao hoán. Các phép biến đổi kết hợp bằng cách nối ma trận, nên rotate() rồi scale() không giống với scale() rồi rotate(). Hãy áp dụng chúng trong cùng một khối theo đúng thứ tự bạn dự định.
Điểm trục mặc định là gốc tọa độ. Nếu bạn bỏ qua điểm trục, phép biến đổi sẽ xoay quanh gốc tọa độ của trang, chứ không phải hình vẽ. Thường thì đó không phải điều bạn muốn, nên hãy truyền điểm trục tường minh.
Trục Y thuộc không gian tác giả. Điểm trục y là khoảng cách tính từ góc trên bên trái trong hệ tọa độ tác giả, và NextPDF chiếu nó sang không gian người dùng gốc. Trộn tọa độ PDF thô với API tác giả sẽ tạo ra kết quả bị lật gương.
Rò rỉ trạng thái. Màu, phông chữ và độ rộng đường nét đặt bên trong một khối biến đổi vẫn tồn tại sau stopTransform(), vì trong bề mặt API này Q chỉ khôi phục CTM. Hãy đặt lại rõ ràng các giá trị này nếu phần phía sau không nên kế thừa chúng, như mẫu chính thức đã làm.

Hiệu năng

Một phép biến đổi phát ra một toán tử cm cùng với cặp q/Q. Mỗi phần tử chỉ vài byte và không thêm chi phí thời gian chạy đáng kể, nên công thức nằm trong ngân sách 1.500 ms / 96 MB. Hồ sơ khả năng tái lập là structural (cấu trúc). Đầu ra chứa một mảng /ID trong trailer, còn siêu dữ liệu tạo tài liệu không ổn định giữa các lần chạy, nên bạn phải chuẩn hóa chúng trước khi so sánh. Bản thân luồng biến đổi là tất định.

Ghi chú bảo mật

Lưu trú dữ liệu & giảm thiểu thông tin nhận dạng cá nhân (PII). Không áp dụng. Công thức này vẽ các hình dạng hình học cơ bản và nhãn ngắn. Nó không xử lý bất kỳ dữ liệu bên ngoài hay dữ liệu cá nhân nào.
Đo từ xa an toàn & làm sạch nhật ký. Công thức ghi ra một dòng tiến trình cố định. Nó không ghi nhật ký bất kỳ nội dung tài liệu nào.
Mô hình mối đe dọa. Không áp dụng. Không có phân tích cú pháp đầu vào, không có mật mã học và không có ranh giới tin cậy. Một phép biến đổi chỉ đơn thuần phát ra luồng nội dung.
Hành vi trong chế độ Federal Information Processing Standards (FIPS). Không áp dụng. Không có thao tác mật mã nào.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Một phép biến đổi nối một ma trận vào CTM bằng toán tử `cm`.	ISO 32000-2	§8.3.4
Các phép biến đổi kết hợp bằng cách nối ma trận, và thứ tự rất quan trọng.	ISO 32000-2	§8.3.4
`q` lưu và `Q` khôi phục trạng thái đồ họa, qua đó giới hạn phạm vi của phép biến đổi.	ISO 32000-2	§8.4.2
Gốc tọa độ của không gian người dùng mặc định nằm ở góc dưới bên trái; một đơn vị là 1/72 inch.	ISO 32000-2	§8.3.2

Công thức này tuân theo các điều khoản được trích dẫn của ISO 32000-2 về trạng thái đồ họa và phép biến đổi. Nó không khẳng định tuân thủ ISO 32000-2 toàn diện; các điều khoản được trích dẫn là những điều khoản duy nhất mà công thức này sử dụng.