Skip to content
PDF Oxide

그래픽, 패턴 & 셰이딩

PDF Oxide는 경로와 도형 그리기를 위한 ContentStreamBuilder, 반복 패턴을 위한 TilingPatternBuilder, 선형 및 방사형 그라디언트를 위한 그라디언트 빌더, 투명도와 블렌드 모드를 위한 ExtGStateBuilder를 통해 저수준 그래픽 프리미티브를 제공합니다.

바인딩 커버리지. FluentPageBuilder의 기본 프리미티브 rect(x, y, w, h), filled_rect(x, y, w, h, color), line(x1, y1, x2, y2)는 v0.3.38부터 Rust, Python, Node, C#, Go, WASM에서 모두 제공됩니다 (DocumentBuilder → 그래픽 프리미티브 참고). 이 페이지의 전체 ContentStreamBuilder 인터페이스 (임의의 경로, 베지어 곡선, 색 공간, TilingPatternBuilder, LinearGradientBuilder / RadialGradientBuilder, ExtGStateBuilder)는 여전히 Rust 전용입니다. 다른 바인딩에서는 DocumentBuilder로 단순 프리미티브를 체이닝하거나, Pdf::from_html_css / Pdf::from_markdown / Pdf::from_images로 PDF를 생성하거나, 커스텀 드로잉이 필요하면 Rust CLI를 호출하세요.

빠른 예제

Rust

use pdf_oxide::writer::{ContentStreamBuilder, LineCap, LineJoin};

let mut builder = ContentStreamBuilder::new();
builder
    .save_state()
    .set_stroke_color(0.0, 0.0, 1.0)    // Blue stroke
    .set_fill_color(0.8, 0.8, 1.0)      // Light blue fill
    .set_line_width(2.0)
    .rect(72.0, 600.0, 200.0, 100.0)
    .fill_and_stroke()
    .restore_state();

ContentStreamBuilder – 드로잉 프리미티브

ContentStreamBuilder는 페이지에 그래픽을 렌더링하기 위한 PDF 콘텐츠 스트림 연산자를 생성합니다.

경로 연산

use pdf_oxide::writer::ContentStreamBuilder;

let mut cs = ContentStreamBuilder::new();

// Move/Line/Curve
cs.move_to(72.0, 700.0)
  .line_to(200.0, 700.0)
  .line_to(200.0, 600.0)
  .close_path()
  .stroke();

// Rectangle
cs.rect(72.0, 500.0, 150.0, 80.0)
  .fill();

// Bezier curve
cs.move_to(72.0, 400.0)
  .curve_to(100.0, 450.0, 200.0, 350.0, 250.0, 400.0)
  .stroke();

색상 연산

// RGB colors (0.0 to 1.0)
cs.set_fill_color(1.0, 0.0, 0.0);      // Red fill
cs.set_stroke_color(0.0, 0.5, 0.0);    // Green stroke

// Grayscale
cs.set_fill_color_gray(0.5);           // 50% gray fill
cs.set_stroke_color_gray(0.0);         // Black stroke

// CMYK
cs.set_fill_color_cmyk(0.0, 1.0, 1.0, 0.0);    // Red in CMYK
cs.set_stroke_color_cmyk(1.0, 0.0, 0.0, 0.0);  // Cyan stroke

선 스타일

use pdf_oxide::writer::{ContentStreamBuilder, LineCap, LineJoin};

let mut cs = ContentStreamBuilder::new();

cs.set_line_width(2.0)
  .set_line_cap(LineCap::Round)
  .set_line_join(LineJoin::Round)
  .set_miter_limit(10.0)
  .set_dash_pattern(vec![5.0, 3.0], 0.0);  // 5pt dash, 3pt gap

LineCap 변형: Butt(기본값), Round, Square

LineJoin 변형: Miter(기본값), Round, Bevel

그래픽 상태

// Save/restore state for isolated operations
cs.save_state()
  .set_fill_color(1.0, 0.0, 0.0)
  .rect(100.0, 100.0, 50.0, 50.0)
  .fill()
  .restore_state();
// State is restored to what it was before save_state()

경로 채우기 및 그리기

메서드 설명
.stroke() 경로 윤곽선 그리기
.fill() 경로 내부 채우기 (non-zero winding)
.fill_even_odd() even-odd 규칙으로 채우기
.fill_and_stroke() 채우기 및 그리기
.fill_and_stroke_even_odd() 채우기(even-odd) 및 그리기
.close_and_stroke() 경로 닫기 후 그리기
.close_fill_and_stroke() 닫기, 채우기, 그리기
.end_path() 칠하지 않고 경로 종료

클리핑

// Clip to rectangle, then draw inside
cs.save_state()
  .rect(100.0, 100.0, 200.0, 200.0)
  .clip()
  .end_path()
  // Everything drawn here is clipped to the rectangle
  .set_fill_color(1.0, 0.0, 0.0)
  .rect(50.0, 50.0, 300.0, 300.0)  // Only visible within clip
  .fill()
  .restore_state();

변환

// Apply transformation matrix [a b c d e f]
cs.save_state()
  .transform(1.0, 0.0, 0.0, 1.0, 100.0, 200.0)  // Translate
  .rect(0.0, 0.0, 50.0, 50.0)
  .fill()
  .restore_state();

ContentStreamOp Enum

최대한의 제어가 필요하면 연산을 직접 구성하세요:

use pdf_oxide::writer::ContentStreamOp;

let ops = vec![
    ContentStreamOp::SaveState,
    ContentStreamOp::SetLineWidth(2.0),
    ContentStreamOp::SetStrokeColorRGB(0.0, 0.0, 1.0),
    ContentStreamOp::MoveTo(72.0, 500.0),
    ContentStreamOp::LineTo(300.0, 500.0),
    ContentStreamOp::Stroke,
    ContentStreamOp::RestoreState,
];

TilingPatternBuilder – 반복 패턴

타일링 패턴은 작은 셀을 영역 전체에 반복합니다.

use pdf_oxide::writer::{TilingPatternBuilder, PatternPaintType, PatternTilingType};

// Striped pattern
let (pattern_dict, content_bytes) = TilingPatternBuilder::new()
    .bbox(0.0, 0.0, 10.0, 10.0)
    .x_step(10.0)
    .y_step(10.0)
    .colored()
    .tiling_type(PatternTilingType::ConstantSpacing)
    .content_bytes(b"0.8 0 0 rg 0 0 5 10 re f".to_vec())
    .build();

구성 메서드

메서드 설명
.bbox(x, y, w, h) 패턴 셀의 경계 상자 설정
.x_step(step) 셀 간 가로 간격
.y_step(step) 셀 간 세로 간격
.step(x, y) 두 간격을 한 번에 설정
.colored() 패턴 콘텐츠에 색상 정의
.uncolored() 패턴 사용 시 색상 지정
.tiling_type(type) 타일링 알고리즘 설정
.matrix(a, b, c, d, e, f) 패턴에 변환 적용
.content_bytes(bytes) 원시 콘텐츠 스트림 바이트 설정
.build() 반환값 (Object, Vec<u8>)

PatternPresets

PDF Oxide는 일반적인 용도를 위한 프리셋 패턴을 제공합니다:

use pdf_oxide::writer::PatternPresets;

// Access presets for common patterns like hatching, dots, etc.

LinearGradientBuilder – 선형 그라디언트

축(선형) 그라디언트 셰이딩을 생성합니다.

use pdf_oxide::writer::{LinearGradientBuilder, GradientStop};
use pdf_oxide::layout::Color;

let (shading_dict, function_dict) = LinearGradientBuilder::new()
    .from(0.0, 0.0)
    .to(468.0, 0.0)
    .add_stop(0.0, Color { r: 1.0, g: 0.0, b: 0.0 })   // Red
    .add_stop(0.5, Color { r: 1.0, g: 1.0, b: 0.0 })   // Yellow
    .add_stop(1.0, Color { r: 0.0, g: 0.0, b: 1.0 })   // Blue
    .extend(true)
    .build();

두 색상 단축 메서드

use pdf_oxide::writer::LinearGradientBuilder;
use pdf_oxide::layout::Color;

let gradient = LinearGradientBuilder::two_color(
    Color { r: 0.0, g: 0.0, b: 0.5 },  // Dark blue
    Color { r: 0.5, g: 0.8, b: 1.0 },   // Light blue
);

구성 메서드

메서드 설명
.from(x, y) 그라디언트 시작점
.to(x, y) 그라디언트 끝점
.add_stop(pos, color) 색상 정지점 추가 (위치 0.0-1.0)
.extend_start(bool) 시작점 이전으로 그라디언트 확장
.extend_end(bool) 끝점 이후로 그라디언트 확장
.extend(bool) 두 확장 플래그를 모두 설정

RadialGradientBuilder – 방사형 그라디언트

원형 그라디언트 셰이딩을 생성합니다.

use pdf_oxide::writer::RadialGradientBuilder;
use pdf_oxide::layout::Color;

let (shading_dict, function_dict) = RadialGradientBuilder::new()
    .center(200.0, 400.0)
    .radius(0.0, 150.0)  // Inner radius 0, outer radius 150
    .add_stop(0.0, Color { r: 1.0, g: 1.0, b: 1.0 })  // White center
    .add_stop(1.0, Color { r: 0.0, g: 0.0, b: 0.5 })  // Dark blue edge
    .build();

ExtGStateBuilder – 투명도 & 블렌드 모드

투명도, 블렌드 모드, 기타 그래픽 상태 파라미터를 제어합니다.

use pdf_oxide::writer::{ExtGStateBuilder, BlendMode};

let gs_dict = ExtGStateBuilder::new()
    .fill_alpha(0.5)             // 50% transparent fill
    .stroke_alpha(0.8)           // 80% opaque stroke
    .blend_mode(BlendMode::Multiply)
    .build();

구성 메서드

메서드 설명
.fill_alpha(a) 채우기 불투명도 (0.0 투명, 1.0 불투명)
.stroke_alpha(a) 선 불투명도
.blend_mode(mode) 블렌드 모드 설정
.line_width(w) 선 너비 재정의
.line_cap(cap) 선 끝 스타일 재정의
.line_join(join) 선 연결 스타일 재정의
.miter_limit(limit) 마이터 한계 재정의
.flatness(f) 평탄도 허용 오차
.overprint_stroke(b) 선 오버프린트 모드
.overprint_fill(b) 채우기 오버프린트 모드

BlendMode 변형

Normal, Multiply, Screen, Overlay, Darken, Lighten, ColorDodge, ColorBurn, HardLight, SoftLight

GradientPresets

일반적인 그라디언트 패턴을 위한 편의 메서드:

use pdf_oxide::writer::GradientPresets;

// Access preset gradient configurations

고급 예제

그라디언트로 차트 배경 그리기

use pdf_oxide::writer::{
    ContentStreamBuilder, LinearGradientBuilder, ExtGStateBuilder, BlendMode,
};
use pdf_oxide::layout::Color;

let mut cs = ContentStreamBuilder::new();

// Draw chart area with rounded-corner appearance
cs.save_state()
  .set_fill_color(0.95, 0.95, 0.97)
  .rect(72.0, 200.0, 468.0, 400.0)
  .fill()
  .restore_state();

// Draw grid lines
cs.save_state()
  .set_stroke_color(0.85, 0.85, 0.85)
  .set_line_width(0.5);

for i in 0..5 {
    let y = 200.0 + (i as f32 * 100.0);
    cs.move_to(72.0, y).line_to(540.0, y).stroke();
}

cs.restore_state();

// Draw data bars
let values = [280.0, 350.0, 180.0, 420.0, 310.0];
let colors = [
    (0.2, 0.5, 0.8),
    (0.3, 0.7, 0.4),
    (0.8, 0.3, 0.3),
    (0.6, 0.4, 0.8),
    (0.9, 0.6, 0.2),
];

for (i, (&val, &(r, g, b))) in values.iter().zip(colors.iter()).enumerate() {
    let x = 100.0 + (i as f32 * 85.0);
    cs.save_state()
      .set_fill_color(r, g, b)
      .rect(x, 200.0, 50.0, val)
      .fill()
      .restore_state();
}

관련 페이지