Image Downloading Utility
Relevant source files
The following files were used as context for generating this wiki page:
The Image Downloading Utility is a specialized toolset developed for the "The Architecture of Open Source Applications" (AOSA) Korean translation project. Its primary purpose is to systematically extract, download, and organize all graphical assets referenced across the multiple volumes of the AOSA series, ensuring that the translated documentation remains visually complete and self-contained.
The utility processes four distinct book volumes: Volume 1, Volume 2, Performance of Open Source Applications (POSA), and 500 Lines or Less. By migrating remote images from aosabook.org to local storage, it enables the translation project to update Markdown references to point to local relative paths rather than external URLs.
Sources: download_summary.md:1-12, CLAUDE.md:1-20
System Architecture
The utility is structured as a pipeline that moves from discovery to local persistence. It utilizes a combination of Python scripts for logic and Bash scripts for high-performance downloading.
Execution Flow
The following diagram illustrates the lifecycle of an image within the utility, from its discovery in a source Markdown file to its final placement in the localized directory structure.
The utility discovers images within the book's Markdown files, maps them to a structured local path, and executes the download using proper HTTP headers.
Sources: download_summary.md:65-75, CLAUDE.md:30-40
Key Components
| Component | Description |
|---|---|
| URL Extractor | Uses Regular Expressions to parse image URLs from Markdown files across all volumes. |
| Downloader Scripts | Python (download_images.py) and Bash (download_images.sh) implementations using requests and wget. |
| Directory Manager | Creates a hierarchical structure matching the book's organizational logic. |
| Mapping System | Maintains image_mapping.json to track the relationship between remote URLs and local paths. |
Sources: download_summary.md:52-63, CLAUDE.md:25-30
Data Organization
The utility organizes assets into a strict hierarchy under the korean_translation/ directory. This structure mirrors the original AOSA volume organization, facilitating easy maintenance and reference updates in the translated text.
This tree represents how the utility categorizes nearly 400 images based on their respective chapters and volumes.
Sources: download_summary.md:15-46, CLAUDE.md:22-29
Image Distribution Statistics
The utility manages a total of 395 identified images. The distribution across volumes is as follows:
- Volume 1: 121 images (e.g., Asterisk, LLVM, Eclipse).
- Volume 2: 118 images (e.g., Git, nginx, PyPy).
- POSA: 62 images focused on performance diagrams.
- 500 Lines: 90 images for various small-scale projects.
- Metadata: 4 book cover images.
Sources: download_summary.md:15-50, korean_translation/metadata/index.html.md:25-100
Implementation Details
Configuration and Headers
To ensure successful retrieval from the aosabook.org servers, the utility implements proper User-Agent headers. This bypasses basic bot-blocking measures and ensures the server treats the script as a legitimate client.
Error Handling and Validation
The system performs size checks to ensure downloads are not truncated. It also maintains a download.log for detailed tracking. During execution, it identifies "Failed downloads" specifically related to hash-named images in the POSA volume that result in 404 errors.
Sources: download_summary.md:52-78
Metadata Mapping
A critical output of the utility is the image_mapping.json file. This serves as a master lookup table for programmatically updating Markdown files.
{
"https://aosabook.org/static/cover1.jpg": "metadata/images/cover1.jpg",
"https://aosabook.org/static/wesnoth/architecture.png": "volume1/images/wesnoth/architecture.png"
}
Sources: download_summary.md:52-55, metadata/index.html.md:27
Conclusion
The Image Downloading Utility serves as a foundational tool for the AOSA Korean translation project. By achieving a 99% success rate in asset migration and providing a comprehensive mapping of 391 successfully downloaded images, it allows translators to work with a local-first asset management strategy, ensuring the long-term reliability and portability of the project's documentation.
Sources: download_summary.md:5-10, download_summary.md:80-85