Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(parse): add large image processing for image parser (#3265)

MaojiaSheng3c70f8d370fc
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 1e9b1365e..2ec4b9565 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -227,7 +227,11 @@
"enable_vlm": true,
"ocr_lang": "eng",
"vlm_model": "gpt-4-vision",
- "max_dimension": 2048,
+ "preview_max_dimension": 2048,
+ "max_file_size_mb": 10.0,
+ "max_tile_dimension_px": 2048,
+ "tile_overlap_px": 2,
+ "large_image_threshold_dimension": 4096
},
"audio": {
"enable_transcription": true,
diff --git a/openviking/parse/parsers/media/constants.py b/openviking/parse/parsers/media/constants.py
index 96f7b4e03..9353cb701 100644
--- a/openviking/parse/parsers/media/constants.py
+++ b/openviking/parse/parsers/media/constants.py
@@ -3,7 +3,7 @@
"""Constants for media parsers."""
# Image extensions supported by ImageParser
-IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".svg"]
+IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".svg", ".tiff", ".tif", ".ico", ".dib", ".icns", ".sgi", ".jp2"]
# Audio extensions supported by AudioParser
AUDIO_EXTENSIONS = [".mp3", ".wav", ".ogg", ".flac", ".aac", ".m4a", ".opus", ".ac3"]
diff --git a/openviking/parse/parsers/media/image.py b/openviking/parse/parsers/media/image.py
index 668d848ee..32a267f01 100644
--- a/openviking/parse/parsers/media/image.py
+++ b/openviking/parse/parsers/media/image.py
@@ -10,6 +10,7 @@ They serve as a design reference for future media parsing capabilities.
For current document parsing (PDF, Markdown, HTML, Text), see other parser modules.
"""
+import io
from pathlib import Path
from typing import List, Optional, Union
@@ -18,7 +19,14 @@ from PIL import Image
from openviking.parse.base import NodeType, ParseResult, ResourceNode
from openviking.parse.parsers.base_parser import BaseParser
from openviking.parse.parsers.media.constants import IMAGE_EXTENSIONS
+from openviking.parse.parsers.media.large_image_processor import (
+ LargeImageResult,
+ process_large_image,
+ save_image_to_bytes,
+)
from openviking.parse.parsers.media.naming import resolve_media_names
+from openviking.parse.parsers.media.utils import _convert_svg_to_png
+from openviking.prompts import render_prompt
from openviking.storage.viking_fs import get_viking_fs
from openviking_cli.utils.config.parser_config import ImageConfig
from openviking_cli.utils.logger import get_logger
@@ -53,7 +61,7 @@ class ImageParser(BaseParser):
4. Create ResourceNode with image metadata and descriptions
5. Return ParseResult
- Supported formats: PNG, JPG, JPEG, GIF, BMP, WEBP, SVG
+ Supported formats: PNG, JPG, JPEG, GIF, BMP, WEBP, SVG, TIFF, ICO, DIB, ICNS, SGI, JP2
"""
def __init__(self, config: Optional[ImageConfig] = None, **kwargs):
@@ -73,7 +81,12 @@ class ImageParser(BaseParser):
async def parse(self, source: Union[str, Path], instruction: str = "", **kwargs) -> ParseResult:
"""
- Parse image file - only copy original file and extract basic metadata, no content understanding.
+ Parse image file:
+ - For large images (>10MB or any dimension >4096px):
+ - Create low-res preview (<=1MB) as the "original"
+ - Split into tiles (<=2048px each)
+ - Generate grid overlay image
+ - For small images: just save as-is with metadata
Args:
source: Image file path
@@ -83,8 +96,8 @@ class ImageParser(BaseParser):
ParseResult with image content
Raises:
- FileNotFoundError: If source file does not exist
- IOError: If image processing fails
+ FileNotFoundError: If source file doesn't exist
+ ValueError: If image processing fails
"""
# Convert to Path object
file_path = Path(source) if isinstance(source, str) else source
@@ -94,35 +107,64 @@ class ImageParser(BaseParser):
viking_fs = get_viking_fs()
temp_uri = viking_fs.create_temp_uri()
- # Phase 1: Generate temporary files
- image_bytes = file_path.read_bytes()
- ext = file_path.suffix
+ # Load image (SVG is converted to PNG first since PIL doesn't support it)
+ # For other formats not natively supported by VLM/embedding, convert to PNG
+ # to ensure end-to-end compatibility with image understanding and vectorization
+ try:
+ file_bytes = file_path.read_bytes()
+ if file_path.suffix.lower() == ".svg" or file_bytes[:4] == b"<svg" or (file_bytes[:5] == b"<?xml" and b"<svg" in file_bytes[:100]):
+ png_bytes = _convert_svg_to_png(file_bytes)
+ if png_bytes is None:
+ raise ValueError(
+ f"SVG files require cairosvg. Install it: pip install cairosvg"
+ )
+ img = Image.open(io.BytesIO(png_bytes))
+ img.verify()
+ img.close()
+ img = Image.open(io.BytesIO(png_bytes))
+ # Save as PNG in output
+ needs_png_conversion = True
+ converted_png_bytes = png_bytes # Save for small-image branch
+ else:
+ # Check if extension is in VLM-natively supported list
+ suffix_lower = file_path.suffix.lower()
+ supported_by_vlm = suffix_lower in {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp"}
+ if supported_by_vlm:
+ img = Image.open(file_path)
+ img.verify() # Verify that it's a valid image
+ img.close() # Close and reopen to reset after verify()
+ img = Image.open(file_path)
+ needs_png_conversion = False
+ else:
+ # Convert unsupported formats to PNG for VLM compatibility
+ img = Image.open(file_path)
+ img.verify()
+ img.close()
+ img = Image.open(file_path)
+ needs_png_conversion = True
+ width, height = img.size
+ format_str = img.format or file_path.suffix[1:].upper() if file_path.suffix else "JPEG"
+ except Exception as e:
+ raise ValueError(f"Invalid image file: {file_path}. Error: {e}") from e
+
+ # Resolve names
+ display_stem, stem, original_filename = resolve_media_names(file_path, file_path.suffix, **kwargs)
+ ext_no_dot = file_path.suffix[1:] if file_path.suffix else "jpg"
+ if needs_png_conversion:
+ # Convert to PNG and change extension for VLM/embedding compatibility
+ ext_no_dot = "png"
+ original_filename = f"{stem}.png"
+ format_str = "png"
- # Resolve the resource name from the caller's resource_name / source_name
- # (falling back to the temp file name) so the filename, URI and title
- # reflect the real upload, not the internal temp id — see resolve_media_names.
- display_stem, stem, original_filename = resolve_media_names(file_path, ext, **kwargs)
- # Root directory name: filename stem + _ + extension (without dot)
- ext_no_dot = ext[1:] if ext else ""
root_dir_name = VikingURI.sanitize_segment(f"{stem}_{ext_no_dot}")
root_dir_uri = f"{temp_uri}/{root_dir_name}"
await viking_fs.mkdir(root_dir_uri, exist_ok=True)
- # 1.1 Save original image with original filename (sanitized)
- await viking_fs.write_file_bytes(f"{root_dir_uri}/{original_filename}", image_bytes)
+ # Process the image (check if large)
+ large_image_result = process_large_image(file_path, img, filename_prefix=stem, config=self.config)
+ img.close()
- # 1.2 Validate and extract image metadata
- try:
- img = Image.open(file_path)
- img.verify() # Verify that it's a valid image
- img.close() # Close and reopen to reset after verify()
- img = Image.open(file_path)
- width, height = img.size
- format_str = img.format or ext[1:].upper()
- except Exception as e:
- raise ValueError(f"Invalid image file: {file_path}. Error: {e}") from e
-
- # Create ResourceNode - metadata only, no content understanding yet
+ # Create root node with metadata
root_node = ResourceNode(
type=NodeType.ROOT,
title=display_stem,
@@ -138,9 +180,70 @@ class ImageParser(BaseParser):
"source_title": display_stem,
"semantic_name": display_stem,
"original_filename": original_filename,
+ "is_large_image": large_image_result.needs_processing,
},
)
+ if large_image_result.needs_processing:
+ # Large image processing mode: save preview, grid, tiles
+ # NOTE: The original file is intentionally NOT saved. Large images can be
+ # hundreds of MB; storing the full-resolution original would exceed storage
+ # budgets. The preview + tiles are the canonical representation. The
+ # `original_filename` metadata field records the original name for reference
+ # but the corresponding file is not persisted.
+ logger.info(f"Processing large image {original_filename}: {width}x{height}")
+
+ # Save low-res preview (original is too large to store)
+ await viking_fs.write_file_bytes(
+ f"{root_dir_uri}/{large_image_result.preview_filename}",
+ large_image_result.preview_bytes
+ )
+ root_node.meta["preview_filename"] = large_image_result.preview_filename
+
+ # Save grid overlay
+ if large_image_result.grid_overlay_bytes:
+ grid_filename = large_image_result.grid_overlay_filename or f"{stem}_grid.jpg"
+ await viking_fs.write_file_bytes(
+ f"{root_dir_uri}/{grid_filename}",
+ large_image_result.grid_overlay_bytes
+ )
+ root_node.meta["grid_overlay"] = grid_filename
+
+ # Create tiles directory
+ if large_image_result.tiles:
+ tiles_dir_name = "tiles"
+ tiles_dir_uri = f"{root_dir_uri}/{tiles_dir_name}"
+ await viking_fs.mkdir(tiles_dir_uri, exist_ok=True)
+
+ # Save all tiles
+ for tile in large_image_result.tiles:
+ if tile.bytes_data:
+ await viking_fs.write_file_bytes(
+ f"{tiles_dir_uri}/{tile.filename}",
+ tile.bytes_data
+ )
+
+ # Update metadata
+ root_node.meta["tiles_dir"] = tiles_dir_name
+ root_node.meta["num_tiles"] = len(large_image_result.tiles)
+ root_node.meta["grid_rows"] = large_image_result.total_rows
+ root_node.meta["grid_cols"] = large_image_result.total_cols
+ root_node.meta["original_width"] = width
+ root_node.meta["original_height"] = height
+
+ else:
+ # Small image: save as PNG if format is not VLM-supported, else as-is
+ if needs_png_conversion:
+ # SVG was already converted to PNG bytes during loading
+ if file_path.suffix.lower() == ".svg":
+ image_bytes = converted_png_bytes
+ else:
+ with Image.open(file_path) as converted_img:
+ image_bytes = save_image_to_bytes(converted_img, format="PNG")
+ else:
+ image_bytes = file_path.read_bytes()
+ await viking_fs.write_file_bytes(f"{root_dir_uri}/{original_filename}", image_bytes)
+
# Phase 3: Build directory structure (handled by TreeBuilder)
return ParseResult(
root=root_node,
@@ -148,7 +251,11 @@ class ImageParser(BaseParser):
temp_dir_path=temp_uri,
source_format="image",
parser_name="ImageParser",
- meta={"content_type": "image", "format": format_str.lower()},
+ meta={
+ "content_type": "image",
+ "format": format_str.lower(),
+ "is_large_image": large_image_result.needs_processing,
+ },
)
# Write to files in temp directory
diff --git a/openviking/parse/parsers/media/large_image_processor.py b/openviking/parse/parsers/media/large_image_processor.py
new file mode 100644
index 000000000..6b2bde001
--- /dev/null
+++ b/openviking/parse/parsers/media/large_image_processor.py
@@ -0,0 +1,513 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""
+Large image processing utilities for OpenViking.
+
+This module provides functionality to:
+1. Detect large images (>10MB or any dimension >4096px)
+2. Split into tiles (<=2048px each)
+3. Split images into grid tiles with overlap
+4. Generate grid overlay images with tile labels
+"""
+
+import io
+from dataclasses import dataclass
+from math import ceil
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from PIL import Image, ImageDraw, ImageFont
+
+from openviking_cli.utils.config.parser_config import ImageConfig
+from openviking_cli.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# =============================================================================
+# Configuration
+# =============================================================================
+
+# Thresholds for triggering large image processing (fallback defaults when no config)
+MAX_FILE_SIZE_MB = 10.0 # 10 MB
+LARGE_IMAGE_THRESHOLD_DIMENSION = 4096 # 4096 pixels
+
+# Target limits for individual tiles
+MAX_TILE_DIMENSION_PX = 2048 # 2048 pixels
+TILE_OVERLAP_PX = 2 # 2 pixels of overlap on each side
+
+# Quality settings for JPEG compression
+PREVIEW_QUALITY_START = 85
+TILE_QUALITY = 90
+
+# Preview dimension fallback (when no config provides preview_max_dimension)
+PREVIEW_MAX_DIMENSION = 2048
+
+
+@dataclass
+class TileInfo:
+ """Information about a single image tile."""
+ row: int
+ col: int
+ x1: int
+ y1: int
+ x2: int
+ y2: int
+ width: int
+ height: int
+ filename: str
+ bytes_data: Optional[bytes] = None
+
+
+@dataclass
+class LargeImageResult:
+ """Result of processing a large image."""
+ needs_processing: bool # True if large image processing was triggered
+ preview_bytes: Optional[bytes] = None # Low-resolution preview image (None for small images)
+ preview_filename: Optional[str] = None
+ grid_overlay_bytes: Optional[bytes] = None
+ grid_overlay_filename: Optional[str] = None
+ tiles: Optional[List[TileInfo]] = None
+ total_rows: int = 0
+ total_cols: int = 0
+ original_width: int = 0
+ original_height: int = 0
+ original_format: str = ""
+
+
+def get_image_size_mb(file_path: Path) -> float:
+ """Get file size in megabytes."""
+ return file_path.stat().st_size / (1024 * 1024)
+
+
+def save_image_to_bytes(img: Image.Image, format: str = "JPEG", quality: int = 90) -> bytes:
+ """Save PIL Image to bytes."""
+ buf = io.BytesIO()
+ if format.upper() == "PNG":
+ img.save(buf, format=format, optimize=True)
+ else:
+ img.save(buf, format=format, quality=quality, optimize=True)
+ return buf.getvalue()
+
+
+def needs_large_image_processing(
+ file_path: Path,
+ width: int,
+ height: int,
+ config: Optional[ImageConfig] = None
+) -> bool:
+ """
+ Determine if an image needs large image processing.
+
+ Args:
+ file_path: Path to the image file
+ width: Image width in pixels
+ height: Image height in pixels
+ config: Optional ImageConfig for custom thresholds
+
+ Returns:
+ True if large image processing is needed
+ """
+ max_file_size_mb = config.max_file_size_mb if config else MAX_FILE_SIZE_MB
+ max_dimension_px = config.large_image_threshold_dimension if config else LARGE_IMAGE_THRESHOLD_DIMENSION
+
+ file_size_mb = get_image_size_mb(file_path)
+ return file_size_mb > max_file_size_mb or width > max_dimension_px or height > max_dimension_px
+
+
+def create_low_res_preview(
+ img: Image.Image,
+ config: Optional[ImageConfig] = None
+) -> bytes:
+ """
+ Create a low-resolution preview of an image.
+
+ Resizes to preview_max_dimension and encodes as JPEG at a fixed quality.
+
+ Args:
+ img: Original PIL Image
+ config: Optional ImageConfig for custom thresholds
+
+ Returns:
+ Preview image bytes in JPEG format
+ """
+ max_dimension_px = config.preview_max_dimension if config else PREVIEW_MAX_DIMENSION
+
+ # Work on a copy
+ img = img.copy()
+ original_width, original_height = img.size
+
+ # Convert to RGB if needed (for PNGs with alpha)
+ if img.mode in ("RGBA", "P"):
+ img = img.convert("RGB")
+
+ # Resize if larger than max dimension
+ if original_width > max_dimension_px or original_height > max_dimension_px:
+ ratio = min(max_dimension_px / original_width, max_dimension_px / original_height)
+ new_width = int(original_width * ratio)
+ new_height = int(original_height * ratio)
+ img = img.resize((new_width, new_height), Image.Resampling.LANCZOS)
+ logger.debug(f"Resized preview to {new_width}x{new_height}")
+
+ return save_image_to_bytes(img, format="JPEG", quality=PREVIEW_QUALITY_START)
+
+
+def calculate_grid_dimensions(
+ width: int,
+ height: int,
+ config: Optional[ImageConfig] = None
+) -> Tuple[int, int]:
+ """
+ Calculate optimal grid dimensions (rows x cols) for an image.
+
+ Tries to keep tiles as square as possible. The only constraint is
+ max_tile_dimension_px; there is no hard cap on total tile count.
+
+ Args:
+ width: Original image width
+ height: Original image height
+ config: Optional ImageConfig for custom thresholds
+
+ Returns:
+ Tuple of (num_rows, num_cols)
+ """
+ max_tile_dimension_px = config.max_tile_dimension_px if config else MAX_TILE_DIMENSION_PX
+ tile_overlap_px = config.tile_overlap_px if config else TILE_OVERLAP_PX
+
+ effective_tile = max_tile_dimension_px - tile_overlap_px * 2
+ if effective_tile <= 0:
+ effective_tile = max_tile_dimension_px
+
+ cols = max(1, ceil(width / effective_tile))
+ rows = max(1, ceil(height / effective_tile))
+
+ return rows, cols
+
+
+def calculate_tile_positions(
+ width: int,
+ height: int,
+ rows: int,
+ cols: int,
+ config: Optional[ImageConfig] = None
+) -> List[Tuple[int, int, int, int]]:
+ """
+ Calculate positions for each tile with overlap.
+
+ Args:
+ width: Original image width
+ height: Original image height
+ rows: Number of grid rows
+ cols: Number of grid columns
+ config: Optional ImageConfig for custom thresholds
+
+ Returns:
+ List of (x1, y1, x2, y2) tuples
+ """
+ tile_overlap_px = config.tile_overlap_px if config else TILE_OVERLAP_PX
+
+ # Calculate base tile size without overlap
+ base_tile_width = ceil(width / cols)
+ base_tile_height = ceil(height / rows)
+
+ tiles = []
+ for row in range(rows):
+ for col in range(cols):
+ # Calculate position with overlap
+ x1 = max(0, col * base_tile_width - tile_overlap_px)
+ y1 = max(0, row * base_tile_height - tile_overlap_px)
+ x2 = min(width, (col + 1) * base_tile_width + tile_overlap_px)
+ y2 = min(height, (row + 1) * base_tile_height + tile_overlap_px)
+
+ # Adjust first/last to ensure no gaps and no out of bounds
+ if col == 0:
+ x1 = 0
+ if col == cols - 1:
+ x2 = width
+ if row == 0:
+ y1 = 0
+ if row == rows - 1:
+ y2 = height
+
+ tiles.append((x1, y1, x2, y2))
+
+ return tiles
+
+
+def split_image_into_tiles(
+ img: Image.Image,
+ rows: int,
+ cols: int,
+ filename_prefix: str = "tile",
+ ext: str = ".jpg",
+ config: Optional[ImageConfig] = None,
+ original_format: str = "JPEG",
+) -> List[TileInfo]:
+ """
+ Split an image into grid tiles.
+
+ Args:
+ img: Original PIL Image
+ rows: Number of grid rows
+ cols: Number of grid columns
+ filename_prefix: Prefix for tile filenames
+ ext: File extension for tiles
+ config: Optional ImageConfig for custom thresholds
+ original_format: Original image format ("PNG" or "JPEG")
+
+ Returns:
+ List of TileInfo objects
+ """
+ width, height = img.size
+ positions = calculate_tile_positions(width, height, rows, cols, config)
+
+ is_png = original_format.upper() == "PNG"
+ save_format = "PNG" if is_png else "JPEG"
+
+ tiles = []
+ tile_idx = 0
+ for row in range(rows):
+ for col in range(cols):
+ x1, y1, x2, y2 = positions[tile_idx]
+ tile_img = img.crop((x1, y1, x2, y2))
+
+ # Convert to RGB if needed (skip for PNG to preserve alpha)
+ if not is_png and tile_img.mode in ("RGBA", "P"):
+ tile_img = tile_img.convert("RGB")
+
+ tile_bytes = save_image_to_bytes(
+ tile_img, format=save_format, quality=TILE_QUALITY
+ )
+
+ filename = f"{filename_prefix}_{row+1}_{col+1}{ext}"
+
+ tile_info = TileInfo(
+ row=row + 1,
+ col=col + 1,
+ x1=x1,
+ y1=y1,
+ x2=x2,
+ y2=y2,
+ width=x2 - x1,
+ height=y2 - y1,
+ filename=filename,
+ bytes_data=tile_bytes
+ )
+ tiles.append(tile_info)
+ tile_idx += 1
+
+ return tiles
+
+
+def _load_cjk_font(font_size: int) -> ImageFont.FreeTypeFont:
+ """Load a font that supports CJK characters, falling back to default."""
+ # Common CJK-capable font paths across platforms
+ font_paths = [
+ # Linux
+ "/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
+ "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+ "/usr/share/fonts/truetype/droid/DroidSansFallbackFull.ttf",
+ "/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc",
+ "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc",
+ "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+ "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+ # macOS
+ "/System/Library/Fonts/PingFang.ttc",
+ "/System/Library/Fonts/Helvetica.ttc",
+ "/System/Library/Fonts/Arial.ttf",
+ "/System/Library/Fonts/Helvetica.ttf",
+ # Windows
+ "C:/Windows/Fonts/msyh.ttc",
+ "C:/Windows/Fonts/simsun.ttc",
+ "C:/Windows/Fonts/arial.ttf",
+ ]
+ for path in font_paths:
+ try:
+ return ImageFont.truetype(path, font_size)
+ except Exception:
+ continue
+ return ImageFont.load_default()
+
+
+def create_grid_overlay(
+ img: Image.Image,
+ rows: int,
+ cols: int,
+ label_prefix: str = "",
+ ext: str = ".jpg",
+ config: Optional[ImageConfig] = None
+) -> bytes:
+ """
+ Create a grid overlay image with tile labels.
+
+ Draws on a resized copy of the image to avoid memory issues with very large originals.
+
+ Args:
+ img: Original PIL Image
+ rows: Number of grid rows
+ cols: Number of grid columns
+ label_prefix: Prefix for labels (e.g., "3_5_")
+ ext: Tile file extension for labels (e.g., ".jpg", ".png")
+ config: Optional ImageConfig for custom thresholds
+
+ Returns:
+ Grid overlay image bytes
+ """
+ tile_overlap_px = config.tile_overlap_px if config else TILE_OVERLAP_PX
+ preview_max_dimension = config.preview_max_dimension if config else PREVIEW_MAX_DIMENSION
+
+ # Resize to a reasonable size for overlay drawing
+ ow, oh = img.size
+ ratio = min(preview_max_dimension / ow, preview_max_dimension / oh, 1.0)
+ new_w = int(ow * ratio)
+ new_h = int(oh * ratio)
+
+ overlay_img = img.copy()
+ if overlay_img.mode in ("RGBA", "P"):
+ overlay_img = overlay_img.convert("RGB")
+ overlay_img = overlay_img.resize((new_w, new_h), Image.Resampling.LANCZOS)
+
+ width, height = overlay_img.size
+ draw = ImageDraw.Draw(overlay_img)
+
+ # Scale positions to the resized image
+ scale_x = new_w / ow
+ scale_y = new_h / oh
+ positions = calculate_tile_positions(ow, oh, rows, cols, config)
+
+ # Draw grid lines (red, 2 pixels)
+ grid_color = (255, 0, 0)
+ line_width = 2
+
+ tile_idx = 0
+ for row in range(rows):
+ for col in range(cols):
+ x1, y1, x2, y2 = positions[tile_idx]
+ tile_idx += 1
+
+ # Scale positions
+ sx1 = int(x1 * scale_x)
+ sy1 = int(y1 * scale_y)
+ sx2 = int(x2 * scale_x)
+ sy2 = int(y2 * scale_y)
+
+ # Draw rectangle around tile
+ draw.rectangle([sx1, sy1, sx2, sy2], outline=grid_color, width=line_width)
+
+ # Calculate label (use ext to match tile file extension)
+ label = f"./tiles/{label_prefix}_{row+1}_{col+1}{ext}"
+
+ # Load a CJK-capable font
+ font = _load_cjk_font(16)
+
+ # Get text size and center
+ bbox = draw.textbbox((0, 0), label, font=font)
+ text_width = bbox[2] - bbox[0]
+ text_height = bbox[3] - bbox[1]
+
+ # Draw centered text
+ center_x = sx1 + (sx2 - sx1) // 2
+ center_y = sy1 + (sy2 - sy1) // 2
+ text_x = center_x - text_width // 2
+ text_y = center_y - text_height // 2
+
+ # Draw background rectangle for text
+ padding = 4
+ draw.rectangle(
+ [text_x - padding, text_y - padding,
+ text_x + text_width + padding, text_y + text_height + padding],
+ fill=(255, 255, 255)
+ )
+ # Draw text
+ draw.text((text_x, text_y), label, fill=grid_color, font=font)
+
+ return save_image_to_bytes(overlay_img, format="JPEG", quality=90)
+
+
+def process_large_image(
+ file_path: Path,
+ img: Optional[Image.Image] = None,
+ filename_prefix: str = "image",
+ config: Optional[ImageConfig] = None
+) -> LargeImageResult:
+ """
+ Process a large image: create preview, split into tiles, generate grid overlay.
+
+ Args:
+ file_path: Path to original image file
+ img: Optional pre-loaded PIL Image
+ filename_prefix: Prefix for output filenames
+ config: Optional ImageConfig for custom thresholds
+
+ Returns:
+ LargeImageResult with processing results
+ """
+ # Use config values or defaults
+ max_file_size_mb = config.max_file_size_mb if config else MAX_FILE_SIZE_MB
+
+ # Load image if not provided
+ own_img = False
+ if img is None:
+ img = Image.open(file_path)
+ own_img = True
+
+ try:
+ width, height = img.size
+ format_str = img.format or "JPEG"
+
+ # Check if processing is needed
+ if not needs_large_image_processing(file_path, width, height, config):
+ return LargeImageResult(
+ needs_processing=False,
+ original_width=width,
+ original_height=height,
+ original_format=format_str
+ )
+
+ logger.info(f"Processing large image: {width}x{height}, {get_image_size_mb(file_path):.2f}MB")
+
+ # Calculate grid dimensions
+ rows, cols = calculate_grid_dimensions(width, height, config)
+ label_prefix = f"{rows}_{cols}"
+ logger.info(f"Grid dimensions: {rows} rows x {cols} cols")
+
+ # Determine tile format: preserve PNG, default to JPEG for others
+ is_png = format_str.upper() == "PNG"
+ tile_ext = ".png" if is_png else ".jpg"
+
+ # Create low-res preview
+ preview_bytes = create_low_res_preview(img, config)
+
+ # Split into tiles
+ tiles = split_image_into_tiles(
+ img, rows, cols,
+ filename_prefix=f"{filename_prefix}_{label_prefix}",
+ ext=tile_ext,
+ config=config,
+ original_format=format_str,
+ )
+
+ # Create grid overlay (use full tile prefix so labels match tile filenames)
+ grid_overlay_bytes = create_grid_overlay(
+ img, rows, cols,
+ label_prefix=f"{filename_prefix}_{label_prefix}",
+ ext=tile_ext,
+ config=config
+ )
+
+ return LargeImageResult(
+ needs_processing=True,
+ preview_bytes=preview_bytes,
+ preview_filename=f"{filename_prefix}_preview.jpg",
+ grid_overlay_bytes=grid_overlay_bytes,
+ grid_overlay_filename=f"{filename_prefix}_grid.jpg",
+ tiles=tiles,
+ total_rows=rows,
+ total_cols=cols,
+ original_width=width,
+ original_height=height,
+ original_format=format_str
+ )
+ finally:
+ if own_img:
+ img.close()
diff --git a/openviking/parse/parsers/media/utils.py b/openviking/parse/parsers/media/utils.py
index c745df3df..bacece337 100644
--- a/openviking/parse/parsers/media/utils.py
+++ b/openviking/parse/parsers/media/utils.py
@@ -25,31 +25,30 @@ def _is_svg(data: bytes) -> bool:
return data[:4] == b"<svg" or (data[:5] == b"<?xml" and b"<svg" in data[:100])
-# SVG to PNG conversion (disabled by default)
-# Uncomment and install dependencies if you need SVG support:
-# Ubuntu/Debian: sudo apt-get install libcairo2 && pip install cairosvg
-# macOS: brew install cairo && pip install cairosvg
-# Or use ImageMagick: sudo apt-get install libmagickwand-dev && pip install Wand
-#
-# def _convert_svg_to_png(svg_data: bytes) -> Optional[bytes]:
-# """Convert SVG to PNG using cairosvg or wand."""
-# try:
-# import cairosvg
-# return cairosvg.svg2png(bytestring=svg_data)
-# except ImportError:
-# pass
-# except OSError:
-# pass # libcairo not installed
-#
-# try:
-# from wand.image import Image as WandImage
-# with WandImage(blob=svg_data, format='svg') as img:
-# img.format = 'png'
-# return img.make_blob()
-# except ImportError:
-# pass
-#
-# return None
+def _convert_svg_to_png(svg_data: bytes) -> Optional[bytes]:
+ """Convert SVG to PNG using cairosvg or wand.
+
+ Dependencies:
+ Ubuntu/Debian: sudo apt-get install libcairo2 && pip install cairosvg
+ macOS: brew install cairo && pip install cairosvg
+ """
+ try:
+ import cairosvg
+ return cairosvg.svg2png(bytestring=svg_data)
+ except ImportError:
+ pass
+ except OSError:
+ pass # libcairo not installed
+
+ try:
+ from wand.image import Image as WandImage
+ with WandImage(blob=svg_data, format='svg') as img:
+ img.format = 'png'
+ return img.make_blob()
+ except ImportError:
+ pass
+
+ return None
def get_media_type(source_path: Optional[str], source_format: Optional[str]) -> Optional[str]:
diff --git a/openviking/parse/registry.py b/openviking/parse/registry.py
index a907936a2..ad57f891c 100644
--- a/openviking/parse/registry.py
+++ b/openviking/parse/registry.py
@@ -75,7 +75,7 @@ class ParserRegistry:
self.register("zip", ZipParser())
self.register("directory", DirectoryParser())
- self.register("image", ImageParser())
+ self.register("image", ImageParser(config=self._parser_configs.get("image")))
self.register("audio", AudioParser())
self.register("video", VideoParser())
@@ -278,6 +278,7 @@ def get_registry() -> ParserRegistry:
"powerpoint": config.markdown,
"excel": config.markdown,
"epub": config.markdown,
+ "image": config.image,
}
except Exception:
parser_configs = None
diff --git a/openviking_cli/utils/config/parser_config.py b/openviking_cli/utils/config/parser_config.py
index bc005f9c1..46fb80b3d 100644
--- a/openviking_cli/utils/config/parser_config.py
+++ b/openviking_cli/utils/config/parser_config.py
@@ -300,14 +300,23 @@ class ImageConfig(ParserConfig):
enable_vlm: Whether to use VLM for visual understanding
ocr_lang: Language for OCR (e.g., "chi_sim", "eng")
vlm_model: VLM model to use (e.g., "gpt-4-vision")
- max_dimension: Maximum image dimension (resize if larger)
+ preview_max_dimension: Maximum dimension for preview resizing (resize if larger)
+ max_file_size_mb: Maximum file size before triggering large image processing
+ max_tile_dimension_px: Maximum dimension for individual tiles
+ tile_overlap_px: Number of pixels to overlap between tiles
+ large_image_threshold_dimension: Dimension threshold for large image detection
"""
enable_ocr: bool = False
enable_vlm: bool = True
ocr_lang: str = "eng"
vlm_model: Optional[str] = None
- max_dimension: int = 2048
+ preview_max_dimension: int = 2048
+ # Large image processing settings
+ max_file_size_mb: float = 10.0 # 10 MB
+ max_tile_dimension_px: int = 2048 # 2048 pixels
+ tile_overlap_px: int = 2 # 2 pixels
+ large_image_threshold_dimension: int = 4096 # 4096 pixels
def validate(self) -> None:
"""
@@ -320,8 +329,16 @@ class ImageConfig(ParserConfig):
super().validate()
# Validate image-specific fields
- if self.max_dimension <= 0:
- raise ValueError("max_dimension must be positive")
+ if self.preview_max_dimension <= 0:
+ raise ValueError("preview_max_dimension must be positive")
+ if self.max_file_size_mb <= 0:
+ raise ValueError("max_file_size_mb must be positive")
+ if self.max_tile_dimension_px <= 0:
+ raise ValueError("max_tile_dimension_px must be positive")
+ if self.tile_overlap_px < 0:
+ raise ValueError("tile_overlap_px must be non-negative")
+ if self.large_image_threshold_dimension <= 0:
+ raise ValueError("large_image_threshold_dimension must be positive")
@dataclass