跳轉到

座標變換

NextPDF 的座標系統基於 PDF 的使用者空間（user space），透過 Current Transformation Matrix（CTM）進行仿射變換。所有幾何操作——平移、縮放、旋轉、傾斜——都表示為 3×3 仿射矩陣的組合。

基本變換

use NextPDF\Graphics\TransformMatrix;

$draw = $document->draw();

// 儲存狀態、套用變換、繪製、還原
$draw->save();

// 平移（移動原點）
$draw->transform()->translate(x: 50.0, y: 100.0);

// 縮放
$draw->transform()->scale(sx: 2.0, sy: 1.5);

// 旋轉（角度，以度為單位，逆時針為正）
$draw->transform()->rotate(
    angle: 45.0,
    center: Position::at(x: 100.0, y: 100.0),
);

// 傾斜
$draw->transform()->skew(angleX: 15.0, angleY: 0.0);

$draw->restore();

矩陣直接操作

use NextPDF\Graphics\TransformMatrix;

// 直接構造仿射矩陣 [a b c d e f]
// | a b 0 |   | scaleX  shearY  0 |
// | c d 0 | = | shearX  scaleY  0 |
// | e f 1 |   | transX  transY  1 |
$matrix = TransformMatrix::create(
    a: 1.0, b: 0.0,
    c: 0.0, d: 1.0,
    e: 50.0, f: 100.0,
);

$draw->transform()->applyMatrix($matrix);

// 矩陣組合
$combined = TransformMatrix::identity()
    ->translate(x: 50.0, y: 0.0)
    ->rotate(angle: 30.0)
    ->scale(sx: 0.8, sy: 0.8);

$draw->transform()->applyMatrix($combined);

SVG 解析與渲染

use NextPDF\Graphics\Vector\SvgRenderer;

// 將 SVG 轉換為 PDF 原生向量指令
$document->vector()->placeSvg(
    svgContent: file_get_contents('/path/to/logo.svg'),
    position: Rectangle::fromXY(x: 20.0, y: 30.0, width: 80.0, height: 40.0),
);

// 控制縮放行為
$document->vector()->placeSvg(
    svgContent: $svgContent,
    position: Rectangle::fromXY(x: 20.0, y: 30.0, width: 80.0, height: 40.0),
    preserveAspectRatio: true,
);

EPS 解析

// 嵌入 EPS 向量圖形（轉換為 Form XObject）
$document->vector()->placeEps(
    epsContent: file_get_contents('/path/to/illustration.eps'),
    position: Rectangle::fromXY(x: 20.0, y: 50.0, width: 120.0, height: 80.0),
    boundingBox: EpsBoundingBox::auto(), // 從 %%BoundingBox 自動讀取
);

OCG 可選內容群組（圖層）

OCG（Optional Content Groups）允許 PDF 閱讀器顯示或隱藏特定內容，常用於多語言版本、印刷標記或互動式圖層：

use NextPDF\Graphics\Ocg\OptionalContentGroup;
use NextPDF\Graphics\Ocg\OcgVisibility;

$ocgManager = $document->ocg();

// 定義圖層
$printLayer = $ocgManager->define(
    name: 'Print Marks',
    visibility: OcgVisibility::Hidden,  // 預設隱藏（螢幕不顯示）
    printState: OcgPrintState::Visible, // 列印時顯示
);

$watermarkLayer = $ocgManager->define(
    name: 'Watermark',
    visibility: OcgVisibility::Visible,
);

// 在圖層中繪製
$ocgManager->beginLayer($printLayer);
$draw->line(/* 裁切線 */);
$ocgManager->endLayer();

$ocgManager->beginLayer($watermarkLayer);
$document->text()->write(text: 'CONFIDENTIAL', /* ... */);
$ocgManager->endLayer();

座標系統轉換

PDF 的原點在頁面左下角（Y 軸向上），與大多數視覺設計工具（左上角，Y 向下）相反。NextPDF 預設使用 PDF 座標系統，但提供轉換輔助工具：

use NextPDF\ValueObjects\Position;
use NextPDF\Graphics\CoordinateConverter;

$pageHeight = $document->context()->currentPageSize->height;

// 將「左上角為原點」的座標轉換為 PDF 座標
$pdfPos = CoordinateConverter::fromTopLeft(
    x: 20.0,
    y: 50.0,
    pageHeight: $pageHeight,
);

參見