Optimizer — 심층 참조

한눈에 보기

이 페이지는 NextPDF\Pro\Optimizer의 공개 표면에 대한 심층 참조입니다. 분석 오케스트레이터, 최적화 레벨, 두 개의 스캐너, 그리고 결과 값 객체를 다룹니다. 매개변수, 기본값, 추정 산술, 실패 모드를 기술합니다. 분석은 읽기 전용입니다. 절감량을 추정할 뿐 출력 문서를 생성하지 않습니다. 워크플로 안내는 먼저 Optimizer 기능 페이지를 참조하십시오.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되어 있으며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

Optimizer에는 기능별 라이선스 플래그가 없습니다. 이것은 Pro 에디션 기능입니다. 최적화 레벨은 라이선스 스위치가 아니라 런타임 매개변수입니다.

공개 API 표면

composer require nextpdf/pro:^3

nextpdf/premium 메타패키지는 nextpdf/pro 코드를 설치합니다. 이 모듈은 NextPDF\Pro\Optimizer 네임스페이스 아래에 있습니다.

심볼	매개변수	기본 동작	반환값	발생 예외 또는 실패 조건	참고
PdfOptimizer::__construct	OptimizationLevel $level = OptimizationLevel::Balanced	지정된 레벨로 옵티마이저를 생성합니다	PdfOptimizer	선언된 것 없음	자체 스캐너 인스턴스를 생성합니다
PdfOptimizer::analyze	string $pdfData	구성된 레벨에서의 읽기 전용 분석	OptimizationResult	100,000,000 바이트를 초과하는 입력에 대해 OverflowException; 유효하지 않은 PDF 데이터에 대해 스캐너에서 InvalidArgumentException	추정만 수행하며 출력 문서를 생성하지 않습니다
PdfOptimizer::withLevel	OptimizationLevel $level	요청된 레벨의 새 옵티마이저를 반환합니다	self	선언된 것 없음	수신 인스턴스는 변경되지 않습니다
OptimizationLevel	Lossless, Balanced, Aggressive 케이스	적극성 레벨의 문자열 기반 열거형	—	—	백킹 값 lossless, balanced, aggressive
OptimizationLevel::label	없음	사람이 읽을 수 있는 레벨 라벨	string	선언된 것 없음	표시용
OptimizationLevel::imageQuality	없음	레벨의 목표 이미지 품질	int	선언된 것 없음	100, 75, 또는 50
OptimizationLevel::deduplicateStreams	없음	레벨이 중복 제거를 활성화하는지 여부	bool	선언된 것 없음	Lossless에 대해서만 false
OptimizationResult::__construct	int $originalSize, int $optimizedSize, int $objectsRemoved, int $imagesBefore, int $imagesAfter, float $processingTimeMs	불변 분석 결과	OptimizationResult	선언된 것 없음	모든 속성은 public 및 readonly입니다
OptimizationResult::savedBytes	없음	원본 크기에서 추정 최적화 크기를 뺀 값	int	선언된 것 없음	바이트
OptimizationResult::savedPercent	없음	백분율 크기 감소	float	선언된 것 없음	원본 크기가 0일 때 0.0
OptimizationResult::summary	없음	여러 줄의 사람이 읽을 수 있는 보고서	string	선언된 것 없음	크기는 B, KB, 또는 MB로 형식화됩니다
ObjectDeduplicator::findDuplicates	string $pdfData	동일한 객체 본문을 SHA-256 해시로 그룹화합니다	list<DuplicateGroup>	%PDF 헤더 누락, 268,435,456 바이트를 초과하는 입력, 또는 500,000개를 초과하는 객체 마커에 대해 InvalidArgumentException	구성원이 둘 이상인 그룹만 반환합니다
ObjectDeduplicator::estimateSavings	list<DuplicateGroup> $groups	그룹별 중복 개수 곱하기 객체 크기를 합산합니다	int	선언된 것 없음	바이트
ImageRecompressor::analyzeImages	string $pdfData	모든 이미지 XObject에 대한 메타데이터를 추출합니다	list<ImageAnalysis>	%PDF 헤더 누락에 대해 InvalidArgumentException	명시적 너비와 높이가 없는 객체는 건너뜁니다
ImageRecompressor::suggestCompression	ImageAnalysis $image, OptimizationLevel $level	필터를 추천하고 절감량을 추정합니다	ImageCompressionSuggestion	선언된 것 없음	레벨 의존적 휴리스틱. 동작 계약을 참조하십시오
DuplicateGroup::__construct	string $contentHash, list<int> $objectNumbers, int $objectSize	불변 중복 그룹 레코드	DuplicateGroup	선언된 것 없음	첫 번째 객체 번호가 보존되는 정규 객체입니다
DuplicateGroup::duplicateCount	없음	그룹 크기에서 정규 객체를 뺀 값	int	선언된 것 없음	병합으로 제거 가능한 객체
ImageAnalysis::__construct	int $objectNumber, int $width, int $height, string $colorSpace, int $bitsPerComponent, string $filter, int $streamSize	불변 이미지별 메타데이터 레코드	ImageAnalysis	선언된 것 없음	필드는 이미지 딕셔너리 항목을 반영합니다
ImageAnalysis::estimatedDpi	float $displayWidthPt	지정된 표시 너비에서의 유효 DPI	float	선언된 것 없음	표시 너비가 0이거나 음수일 때 0.0
ImageAnalysis::isOverResolution	float $displayWidthPt, int $targetDpi = 300	목표 DPI를 초과하는 다운샘플링 후보를 표시합니다	bool	선언된 것 없음	엄격한 초과 비교
ImageCompressionSuggestion::__construct	int $objectNumber, string $currentFilter, string $suggestedFilter, int $estimatedSavings, string $reason	불변 추천 레코드	ImageCompressionSuggestion	선언된 것 없음	reason은 사람이 읽을 수 있는 설명 텍스트입니다

진입점 시그니처

final class PdfOptimizer
{
    public function __construct(
        private OptimizationLevel $level = OptimizationLevel::Balanced,
    )

    public function analyze(string $pdfData): OptimizationResult

    public function withLevel(OptimizationLevel $level): self
}

enum OptimizationLevel: string
{
    case Lossless = 'lossless';
    case Balanced = 'balanced';
    case Aggressive = 'aggressive';

    public function label(): string

    public function imageQuality(): int

    public function deduplicateStreams(): bool
}

final readonly class OptimizationResult
{
    public function __construct(
        public int $originalSize,
        public int $optimizedSize,
        public int $objectsRemoved,
        public int $imagesBefore,
        public int $imagesAfter,
        public float $processingTimeMs,
    )

    public function savedBytes(): int

    public function savedPercent(): float

    public function summary(): string
}

final class ObjectDeduplicator
{
    public function findDuplicates(string $pdfData): array

    public function estimateSavings(array $groups): int
}

final class ImageRecompressor
{
    public function analyzeImages(string $pdfData): array

    public function suggestCompression(
        ImageAnalysis $image,
        OptimizationLevel $level,
    ): ImageCompressionSuggestion
}

동작 계약

오케스트레이션

PdfOptimizer::analyze는 원시 PDF 바이트를 받으며 읽기 전용입니다. 먼저 신뢰할 수 없는 입력을 100,000,000 바이트로 제한합니다. 크기를 초과하는 입력은 어떤 스캔이 실행되기 전에 OverflowException을 발생시킵니다. 그런 다음 레벨이 허용할 때 중복 제거 분석을 실행하고, 이미지 분석은 항상 실행하며, 둘 다 하나의 OptimizationResult로 집계합니다. withLevel은 새 옵티마이저를 반환하며, 인스턴스는 절대 변경되지 않습니다.

레벨 의미 체계

레벨	이미지 품질 목표	중복 제거	의도
Lossless	100%	꺼짐	품질 손실 없음. 바이트 안정 출력 의도
Balanced	75%	켜짐	적당한 품질 절충. 기본값
Aggressive	50%	켜짐	최대 감소. 다운샘플링. 가시적 품질 손실

Lossless는 출력이 바이트 안정 상태를 유지할 수 있도록 중복 제거를 건너뜁니다. 품질 목표는 아래의 이미지 제안 산술에 입력됩니다.

중복 제거 분석

중복 제거기는 세대 0 간접 객체 정의(N 0 obj부터 endobj까지)를 스캔합니다. 각 본문은 주변 공백이 잘리고, SHA-256으로 해시되며, 해시별로 그룹화됩니다. 따라서 패딩만 다른 정의도 여전히 일치합니다. 구성원이 둘 이상인 그룹만 반환됩니다. 정규 객체를 제외한 모두를 제거할 수 있으므로, 그룹별 추정 절감량은 중복 개수 곱하기 단일 본문 크기와 같습니다.

이미지 분석

객체의 본문에 /Subtype /Image(내부 공백 유무와 무관)가 포함되면 해당 객체는 이미지로 취급됩니다. 너비와 높이는 필수입니다. 둘 중 하나라도 누락된 객체는 건너뜁니다. 색 공간은 DeviceRGB, 컴포넌트당 비트는 8, 필터는 없을 때 빈 문자열로 기본 설정됩니다. 스트림 크기는 stream과 endstream 마커 사이에서 측정됩니다. 인라인 스트림을 찾지 못하면 대신 /Length 값을 사용합니다.

제안 휴리스틱

• Lossless 레벨에서는 현재 필터가 유지되고 추정 절감량은 0입니다.
• DCTDecode 소스의 경우, 제안은 레벨의 품질로 재인코딩합니다. 추정치는 스트림 크기 곱하기 (1 − 품질/100) 곱하기 0.5입니다.
• FlateDecode 소스의 경우, 제안은 DCTDecode로 변환합니다. 추정치는 Balanced에서 스트림 크기의 40%, Aggressive에서 60%입니다.
• 그 밖의 필터 또는 필터 없음의 경우, 제안은 FlateDecode로 변환합니다. 추정치는 스트림 크기의 20%입니다.

결과 산술

• 제거된 객체는 모든 중복 그룹에 걸쳐 정규 첫 번째 객체를 넘어서는 구성원의 합과 같습니다.
• 총 절감량은 중복 제거 절감량 더하기 이미지별 제안 추정치와 같습니다.
• 추정 최적화 크기는 원본 크기에서 총 절감량을 뺀 값이며, 0으로 하한 처리됩니다. 절감량은 음수가 아니므로, 추정치는 원본 크기를 절대 초과하지 않습니다.
• 최적화 후 이미지 수는 분석된 이미지를 포함하는 각 중복 그룹에 대해 해당 그룹의 중복 구성원 수를 뺍니다. 이 수는 0으로 하한 처리됩니다.
• 처리 시간은 단조 시계로 측정되어 밀리초 단위로 보고됩니다.

DPI 추정기는 픽셀 너비를 인치 단위 표시 너비(인치당 72포인트)로 나눕니다. 0이거나 음수인 표시 너비는 0.0을 산출합니다. 초과 해상도 술어는 추정치를 목표, 기본값 300 DPI와 비교합니다.

엣지 케이스 및 실패 모드

• analyze는 잠재력만 보고합니다. 최적화된 출력은 Writer 모듈로 생성하십시오.
• 빈 입력, 또는 %PDF 헤더로 시작하지 않는 입력은 InvalidArgumentException으로 실패합니다.
• 100,000,000 바이트를 초과하는 입력은 어떤 스캔이 실행되기 전에 오케스트레이터 정문에서 OverflowException으로 실패합니다.
• 중복 제거기는 268,435,456 바이트를 초과하는 입력과 500,000개를 초과하는 객체 마커를 독립적으로 거부합니다. 둘 다 InvalidArgumentException으로 페일 클로즈드 거부합니다. 어떤 것도 잘리거나 부분적으로 스캔되지 않습니다.
• 세대 0 객체 정의만 참여합니다. 세대 번호가 0이 아닌 객체는 스캔되지 않습니다.
• 닫는 endobj 마커가 없는 정의는 건너뜁니다.
• 명시적 너비와 높이가 없는 이미지 객체는 이미지 보고서에서 제외됩니다.
• 모든 절감 수치는 측정된 재압축 결과가 아니라 객체 메타데이터에서 도출된 휴리스틱입니다.
• lossless 레벨은 의도적으로 작은 감소를 보고합니다. 품질을 보존하고 중복 제거를 건너뜁니다.
• 분석은 임베드된 콘텐츠를 디코딩하거나 실행하거나 렌더링하지 않습니다. 객체 구조와 메타데이터만 읽습니다.
• 사용되는 유일한 암호화 프리미티브는 중복 콘텐츠 그룹화를 위한 SHA-256입니다. 이 모듈은 FIPS 특정 동작을 정의하지 않습니다.

적합성

두 스캐너 모두 ISO 32000-2:2020의 PDF 객체 및 이미지 모델에 대해 작동합니다. 중복 제거는 간접 객체 정의를 대상으로 합니다. 그 식별자 구조는 이 페이지의 인용 레코드에 인용된 ISO 32000-2:2020, 7.3.10에 정의되어 있습니다. 이미지 분석은 이미지 딕셔너리가 명시적으로 기술하는 매개변수 — 너비, 높이, 컴포넌트당 비트 — 를 ISO 32000-2:2020, 8.9.4에 따라 읽습니다. 이 또한 인용되어 있습니다.

이 진술은 인용된 절에 대한 기능을 설명합니다. NextPDF는 어떠한 적합성 인증도 보유하지 않으며, 절에 대한 지원은 인증 주장이 아닙니다.

개발 노트

• 모듈 소스에는 @since 1.9.0이 있습니다. 이 참조는 nextpdf/pro 3.1.0에 포함되어 출시된 표면을 문서화합니다.
• 모든 클래스는 final입니다. 결과 및 분석 레코드는 readonly 값 객체입니다. 변경하는 대신 새 인스턴스를 생성하십시오.
• 기본 레벨은 Balanced입니다. 생성자 또는 with 스타일 메서드를 통해 다른 레벨을 선택하십시오.
• 정문 입력 경계는 NextPDF 입력 표면 전반에 걸쳐 공유되는 Core 입력 크기 가드에 의해 적용됩니다.
• 분석은 이미 메모리에 있는 바이트에 대한 문자열 기반입니다. 이 모듈은 파일 시스템이나 네트워크 접근을 수행하지 않습니다.
• 내부 메커니즘 세부 사항은 소스 저장소의 내부 문서에 남아 있으며 이 설명서의 범위를 벗어납니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.

함께 보기

• Optimizer — 워크플로 안내와 코드 샘플을 위한 기능 페이지.
• Writer — 심층 참조 — 최적화된 출력 문서를 생성합니다.
• Accelerator — 심층 참조 — 이 모듈의 의미론으로 사이드카 오프로드를 통한 배치 최적화.