PDF to Images

Công cụ dòng lệnh (CLI) chuyển đổi từng trang của các file PDF trong một thư mục thành ảnh. Người dùng truyền từ bên ngoài CLI trang bắt đầu (--start) và trang kết thúc (--end) để chỉ định khoảng trang cần cắt (chuyển) thành ảnh.

Yêu cầu hệ thống

Script sử dụng công cụ pdftoppm và pdfinfo từ gói poppler-utils (không cần pip). Cài đặt tùy hệ điều hành:

• Debian/Ubuntu: sudo apt-get install -y poppler-utils
• Fedora: sudo dnf install -y poppler-utils
• macOS: brew install poppler
• Windows: cài poppler và thêm vào PATH

Python >= 3.10.

Cài đặt

pip install -e .

Hoặc chạy trực tiếp module (không cần cài đặt):

python -m pdf_to_images --help

Chạy test (yêu cầu pytest):

pip install -e ".[dev]"
pytest

Cách sử dụng

Bạn có thể truyền một file PDF hoặc một thư mục chứa PDF vào tham số vị trí SOURCE (hoặc --docs). Mọi tham số còn lại đều có mặc định, ảnh xuất vào ./out (tự động tạo nếu chưa có). Ảnh của mỗi PDF được ghi vào một subfolder riêng đặt theo tên file PDF: ./out/<tên_pdf>/. Mỗi lần chạy sẽ xóa sạch ảnh cũ trong subfolder của PDF đó trước khi ghi ảnh mới (các PDF khác không bị ảnh hưởng).

pdf-to-images                                    # đọc ./docs, xuất ./out
pdf-to-images path/to/file.pdf                   # chỉ 1 file cụ thể
pdf-to-images path/to/folder                     # cả thư mục PDF

Nếu dùng môi trường ảo uv:

uv run pdf-to-images path/to/file.pdf --start 1 --end 5

Ảnh xuất ra có tên dạng <tên_file>-<số_trang>.png trong thư mục ./out/<tên_file>/.

Tham số CLI

Tham số	Mặc định	Mô tả
SOURCE	./docs	File PDF hoặc thư mục chứa PDF (tham số vị trí, tuỳ chọn)
--docs	./docs	Thư mục chứa PDF (dùng thay cho SOURCE)
--start	1	Trang bắt đầu chuyển đổi (1-indexed, inclusive)
--end	cuối PDF	Trang kết thúc chuyển đổi (1-indexed, inclusive)
--format	png	Định dạng ảnh: png, jpeg, tiff
--dpi	150	Độ phân giải ảnh
--output	./out	Thư mục lưu ảnh kết quả (tạo tự động)
-v/--verbose	tắt	Bật log mức DEBUG
--version	-	In phiên bản

Chỉ các trang trong khoảng [start, end] mới được xử lý.

Ví dụ

Chuyển trang 61–65 của một file cụ thể:

pdf-to-images ./docs/Designing_Machine_Learning_Systems.pdf --start 61 --end 65

Chuyển trang 1 đến 2 của toàn bộ PDF trong thư mục (ảnh xuất vào ./out):

pdf-to-images --start 1 --end 2

Chuyển toàn bộ PDF với độ phân giải cao:

pdf-to-images --dpi 300

Cấu trúc dự án

.
├── pdf_to_images/        # Package chính
│   ├── __init__.py
│   ├── cli.py            # Parse CLI + entry point (main)
│   ├── discovery.py      # Tìm kiếm file PDF
│   ├── pdf_utils.py      # pdfinfo / pdftoppm wrappers
│   ├── exceptions.py     # Exception tùy biến
│   └── logging_config.py # Cấu hình logging
├── tests/                # Test pytest
├── docs/                 # Thư mục chứa PDF đầu vào (dữ liệu)
├── out/                  # Ảnh xuất ra (tạo tự động, đã .gitignore)
├── pyproject.toml
├── .gitignore
├── README.md
└── REFACTOR.md