Phantom Image Optimizer¶

What Does This Tool Do?¶

Phantom Image Optimizer is the standalone image optimization tool of Phantom Documentation Kit.

Main Purpose¶

Developed for optimizing images used in documentation projects. Large-sized images cause documentation pages to load slowly. This tool significantly reduces file sizes while preserving image quality.

Powerful Infrastructure¶

Leverages the industrial power of the Sharp library. This provides:

Documentation images
Website photographs
Images used in blog content
E-commerce product images
All images requiring optimization in your digital projects

professional-level optimization.

Let's Get Started!¶

Step 1: Installation¶

System Requirements¶

Node.js Version¶

Minimum Node.js version: 22.x or higher required
To check your Node.js version: node --version
To download the appropriate Node.js version: https://nodejs.org/en/download

macOS System Packages¶

The following packages must be installed for the Sharp library to work properly:

You can easily install the required packages with Homebrew.

brew install vips pkg-config

brew install libjpeg libpng webp giflib libtiff

Linux System Packages¶

For Ubuntu/Debian based systems:

sudo apt-get update && sudo apt-get install -y \
    libvips42 libvips-dev \
    libjpeg-dev libpng-dev libwebp-dev \
    libgif-dev libtiff-dev \
    pkg-config build-essential

For RHEL/CentOS/Fedora based systems:

sudo yum install -y \
    vips vips-devel \
    libjpeg-turbo-devel libpng-devel libwebp-devel \
    giflib-devel libtiff-devel \
    pkgconfig gcc-c++ make

Phantom Documentation Kit Docker Mode¶

Phantom Documentation Kit includes the necessary tools and Node version to run this tool in the Docker image by default. After running serve in Docker mode, you can follow the installation steps inside the running container to run the tool.

Note that you need to follow the installation steps for this tool again each time you run serve.

Package Installation¶

Open the terminal and navigate to the project directory, then navigate to the Phantom Image Optimizer directory by typing:

cd tools/image-optimizer

Install the required npm packages with the following command:

npm install

If you want to use it globally, apply the following command.

npm link

Then you can run it anywhere directly with the phantom-optimize command.

phantom-optimize ./images

Step 2: Our First Optimization!¶

Simplest Usage¶

Optimize the images in the 'images' directory with the following command:

node optimize.js ../../docs/assets/static/images

If you wish, you can save the optimized images to a different directory while preserving the originals.

node optimize.js \
         ../../docs/assets/static/images \
         --output ../../docs/assets/static/optimized_images

Quick Tips¶

If You Say "My Files Are Too Large":¶

node optimize.js ./photos --quality 60

If You Say "I Don't Want to Lose the Originals":¶

node optimize.js ./original-photos --output ./optimized

If You Say "I Want to Test First":¶

node optimize.js ./photos --dry-run

If You Say "Only Optimize JPEGs":¶

node optimize.js ./photos --formats jpeg

Practical Experiments¶

Speed Test¶

Process 4 files simultaneously (turbo mode!)

node optimize.js ./photos --concurrency 4

Detailed Information¶

Tell me everything!

node optimize.js ./photos --verbose

Silent Mode¶

Only show errors, ignore the rest

node optimize.js ./photos --silent

Our Real Test Results¶

How Does Our Test System Work?¶

Simple Explanation: A test script was written that comprehensively tests all features of Phantom Image Optimizer under real-world conditions.

Would You Like to Run the Test Script?¶

Make sure you are in the tools/image-optimizer directory and navigate to the 'testing' folder where the test script is located:

cd testing

There are different ways to run the test script, you can test it by running it as you wish. If you want, you can save the results at the end of the tests to compare both the report and the images for comparison.

Run the test script:

python test_comprehensive.py

For more detailed error tracking and outputs:

python test_comprehensive.py --verbose

If you want to keep test results for comparison:

python test_comprehensive.py --keep-artifacts

What Exactly Does the Test Do?¶

First downloads photos - 7390 cat-dog photos from Oxford University
Performs 15 different tests - Tests critical situations according to real user usage
Writes report - Saves results to report file
Cleans up - Optionally deletes test files, or keeps them for comparison

Why Oxford Pet Dataset?¶

Let's be frank: Real photos were needed for testing. Oxford University's cat-dog photos were chosen because:

Always accessible - An academic study, link is always accessible
Real photos - Images selected from real life for an academic study
7390 photos - Both quick test (15 of them) and large test (all) can be done
Everyone can use - Open source, free, for scientific purposes

This makes the tests realistic and results can be easily compared!

Real Test Results¶

$ python test_comprehensive.py --verbose

Phantom Image Optimizer

Test Terminal Recording

If you want to see the comprehensive and raw outputs of the real test results, you can check the files at the following file locations.

testing/reports/TEST_REPORT_20250807_092504.md
testing/recordings/test_comprehensive_20250807_092345.cast

High Quality Optimization (Quality 90)¶

Command:

$ node optimize.js \ ./testing/data/mini_dataset \ -q 90 \ --output ./testing/outputs/output_high_quality

Real Results:

15 images processed
Processing time: 0.35 seconds
Total size: 1.29MB → 562.3KB (57.3% reduction)

Sample files:
├── scottish_terrier_43.jpg: 172.93KB → 83.38KB (51.8% reduced)
├── shiba_inu_95.jpg: 140.04KB → 55.78KB (60.2% reduced)
├── pomeranian_38.jpg: 133.27KB → 41.2KB (69.1% reduced)
└── Birman_134.jpg: 103.85KB → 34.48KB (66.8% reduced)

Medium Quality Optimization (Quality 75)¶

Command:

$ node optimize.js \ ./testing/data/mini_dataset \ -q 75 \ --output ./testing/outputs/output_medium_quality

Real Results:

15 images processed
Processing time: 0.29 seconds
Total size: 1.29MB → 312.3KB (76.3% reduction)

Sample files:
├── scottish_terrier_43.jpg: 172.93KB → 48.66KB (71.9% reduced)
├── pomeranian_38.jpg: 133.27KB → 18.81KB (85.9% reduced!)
└── Birman_134.jpg: 103.85KB → 15.34KB (85.2% reduced!)

Aggressive Optimization (Quality 60)¶

Command:

$ node optimize.js \ ./testing/data/mini_dataset \ -q 60 \ --output ./testing/outputs/output_low_quality

Real Results:

15 images processed
Processing time: 0.22 seconds
Total size: 1.29MB → 220.17KB (83.3% reduction!)

Sample files:
├── pomeranian_38.jpg: 133.27KB → 12.43KB (90.7% reduced!!)
├── Birman_134.jpg: 103.85KB → 10.22KB (90.2% reduced!!)
└── British_Shorthair_60.jpg: 101.52KB → 14.48KB (85.7% reduced!)

Practical Usage Table¶

What I Want	Copy Command
Simplest Usage	`node optimize.js ./photos`
High Quality	`node optimize.js ./photos -q 90`
Fast and Small	`node optimize.js ./photos -q 60`
Safe Test	`node optimize.js ./photos --dry-run`
Backup and Optimize	`node optimize.js ./photos -o ./optimized`
Only JPEG	`node optimize.js ./photos -f jpeg`
Turbo Mode	`node optimize.js ./photos -c 8`
Work Silently	`node optimize.js ./photos --silent`