벡터 그래픽 그리기 — 도형, 색상, 선 스타일

한눈에 보기

이 레시피는 채워진 기본 도형과 윤곽선만 있는 기본 도형, 즉 직사각형, 모서리가 둥근 직사각형, 원, 타원, 선을 그립니다. 각 도형마다 채우기 색상, 윤곽선(stroke) 색상, 선 너비를 설정합니다. 이 레시피는 examples/06-colors-and-drawing.php를 기준으로 합니다.

각 기본 도형은 ISO 32000-2 경로(path) 객체에 매핑됩니다. 경로 객체는 직선 세그먼트와 곡선 세그먼트로 구성된 도형입니다. 경로 객체는 도형의 윤곽선을 그릴지, 채울지, 둘 다 수행할지를 결정하는 페인팅 연산자로 끝납니다.

설치

composer require nextpdf/core:^3

선택적 확장은 필요하지 않습니다. 그리기 및 색상 API는 1.0.0부터 안정적이며, 8.1–8.4 백포트 매트릭스에서 실행됩니다.

개념 개요

상태를 설정한 다음 그립니다. setFillColor(), setDrawColor(), setLineWidth()는 그래픽 상태를 갱신합니다. 다음에 오는 rect(), circle(), ellipse(), roundedRect() 또는 line()이 그 상태를 사용합니다. 도형 메서드는 스타일 인수를 받습니다. 'F'는 채우고, 'S'는 윤곽선을 그리며(기본값), 'DF'/'FD'는 둘 다 수행합니다. 내부적으로 채워진 직사각형은 경로 구성 re 연산자에 이어 채우기 페인팅 연산자를 사용합니다. ISO 32000-2 §8.5.3은 주요 경로 페인팅 연산자로 윤곽선 그리기에 S를, 채우기에 f를 규정합니다.

색상은 디바이스 색상입니다. setFillColor(r, g, b)는 DeviceRGB를 선택합니다. ISO 32000-2 §8.6.4.3은 rg를 DeviceRGB 비윤곽선(non-stroking) 색상 연산자로, g를 그에 해당하는 DeviceGray 연산자로 정의합니다. 인수가 하나인 setFillColor($v)는 회색조 값입니다. 선 너비의 기본값은 1.0이고, 대시 패턴의 기본값은 실선입니다(§8.4.3.6).

API 표면

API 표면은 PHPDoc에서 자동으로 생성됩니다. 이 레시피는 다음 메서드를 사용합니다.

rect(float $x, float $y, float $w, float $h, string $style = 'S'): static
roundedRect(float $x, float $y, float $w, float $h, float $r, string $style = 'S'): static
circle(float $x, float $y, float $r, string $style = 'S'): static
ellipse(float $x, float $y, float $rx, float $ry, string $style = 'S'): static
line(float $x1, float $y1, float $x2, float $y2): static
setFillColor(int $r, int $g = -1, int $b = -1): static / setDrawColor(...)
setLineWidth(float $width): static

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->setFillColor(30, 58, 138);
$doc->rect(20, 30, 60, 40, 'F');          // filled rectangle

$doc->setDrawColor(217, 119, 6);
$doc->setLineWidth(1.0);
$doc->circle(140, 50, 20, 'S');           // stroked circle

$doc->setLineWidth(0.3);
$doc->line(20, 90, 190, 90);              // thin rule

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/vector.pdf');

코드 샘플 — 프로덕션

하니스에서 바로 실행할 수 있는 완전한 예제입니다. 이 예제는 NEXTPDF_COOKBOOK_OUTPUT을 따르며, 자체적으로 엔트로피를 추가하지 않습니다.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Colors and Drawing');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Colors and Drawing', newLine: true);
$doc->ln(5);

// --- Filled rectangles: set fill colour, then draw with style 'F' ---
$palette = [
    [30, 58, 138], [217, 119, 6], [30, 27, 75],
    [239, 66, 35], [21, 128, 61],
];
$x = 15.0;
$rowY = $doc->getY();
foreach ($palette as [$r, $g, $b]) {
    $doc->setFillColor($r, $g, $b);
    $doc->rect($x, $rowY, 30, 20, 'F');
    $x += 35.0;
}
$doc->ln(28);

// --- Outlined shapes: set draw colour + line width, draw with 'S' ---
$doc->setDrawColor(30, 58, 138);
$doc->setLineWidth(0.5);
$y = $doc->getY();
$doc->rect(15, $y, 30, 25, 'S');
$doc->roundedRect(55, $y, 30, 25, 5, 'S');
$doc->circle(110, $y + 12.5, 12.5, 'S');
$doc->ellipse(150, $y + 12.5, 18, 10, 'S');
$doc->ln(33);

// --- Lines at three widths ---
$y = $doc->getY();
$doc->setDrawColor(0);
$doc->setLineWidth(0.2);
$doc->line(15, $y, 195, $y);
$doc->setLineWidth(0.8);
$doc->line(15, $y + 5, 195, $y + 5);
$doc->setLineWidth(1.5);
$doc->line(15, $y + 12, 195, $y + 12);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/vector.pdf';
$doc->save($out);

echo "Created vector.pdf\n";

예외 상황 및 주의 사항

스타일의 기본값은 윤곽선 그리기입니다. 스타일 인수를 생략하면 도형은 윤곽선으로 그려집니다('S'). 보이지 않는 것처럼 보이는 도형은 대개 그리기 색상이 설정되지 않은 채 그려졌거나, 페이지 배경색으로 채워진 것입니다. 채우려면 'F'를 전달합니다.
색상 상태는 유지됩니다. setFillColor()는 변경할 때까지 적용된 상태로 유지됩니다. 관련 없는 다음 블록으로 넘어가기 전에 색상을 재설정합니다(예: setFillColor(255)). 그렇지 않으면 색상이 그대로 이어집니다.
회색조와 RGB 오버로드 구분. setFillColor(128)는 회색조 값입니다. setFillColor(128, 0, 0)는 RGB입니다. 인수가 하나인 형태는 “빨강 128”이 아닙니다.
API에서 Y축은 위에서 아래로 진행합니다. 그리기 헬퍼는 문서의 왼쪽 위 원점을 사용합니다. 엔진이 이를 PDF의 왼쪽 아래 사용자 공간으로 대신 매핑해 줍니다.

성능

각 기본 도형은 몇 개의 콘텐츠 스트림 연산자로 표현됩니다. 페이지당 수천 개의 도형도 2000ms / 64MB 예산 안에 충분히 들어옵니다. 비용은 기본 도형 수에 비례해 선형으로 증가합니다. 래스터화가 없으므로 출력은 벡터로 유지됩니다.

보안 참고 사항

이 레시피는 코드에서 지정한 도형만 그립니다. 입력을 파싱하지 않으며 네트워크에 접근하지 않습니다. 신뢰할 수 없는 데이터에서 가져온 좌표는 모두 범위 검사를 수행합니다. 범위 검사는 악의적인 값 때문에 마크가 페이지 바깥 멀리 밀려나는 일을 막아 줍니다.

규격 준수

설명	사양	조항
경로 객체는 직선, 직사각형, 베지에 곡선으로 이루어지며 페인팅 연산자로 끝납니다.	ISO 32000-2	§8.5
`S`는 경로의 윤곽선을 그리고 `f`는 경로를 채웁니다.	ISO 32000-2	§8.5.3
`rg`는 DeviceRGB 비윤곽선 색상을 설정하고, `g`는 DeviceGray를 설정합니다.	ISO 32000-2	§8.6.4.3
대시 패턴의 초깃값은 `[] 0`이며, 실선입니다.	ISO 32000-2	§8.4.3.6

재현성 프로필 — 구조적. 벡터 그리기는 자체적인 엔트로피가 없습니다. 그렇더라도 저장되는 모든 문서에는 트레일러 /ID와 날짜 원자가 포함됩니다. ISO 32000-2 §8.3.4는 또한 그래픽 상태 연산자의 정확한 배열이 의미상 중요하지 않다고 명시하므로, 정규화기는 동등한 상태를 재정렬할 수 있습니다. 정직하게 주장할 수 있는 범위는 qpdf 정규화 이후의 구조적 동등성입니다. 이 레시피는 NextPDF가 그 구조를 생성하는 방식을 설명합니다. 이 레시피는 ISO 32000-2 준수를 포괄적으로 주장하지 않습니다.

상업적 맥락

해당 없음. 벡터 그리기는 Premium 게이트가 적용되지 않는 Core 기능입니다.