Hitting a file-size window with canvas.toBlob: fitting passport photos into 54–240 KB

Government photo upload forms have strict file size requirements. The US DS-160 visa form accepts a JPEG up to 240 KB with a compression ratio of no more than 20:1. China's online visa form requires a file size between 40 and 120 KB. A 30 KB file is rejected for being too compressed, while a 300 KB file is rejected for being too large.

Users typically fix this issue by re-saving the image in an image editor until it meets the requirements. When building an automatic tool, this becomes a search problem. Here's how to handle it in the browser without involving a server.

First, convert the compression ratio limit into a byte window. The compression ratio is the ratio of raw bytes to file bytes. For a 600x600 pixel photo, the raw bitmap size is 1,080,000 bytes. With a maximum compression ratio of 20:1, the file must be at least 54,000 bytes. This creates a minimum and maximum byte range for the file size.

One important note is that official pages sometimes don't specify whether "KB" refers to 1000 or 1024 bytes. To account for this uncertainty, use 1024 for the minimum and 1000 for the maximum. The file should pass whichever way the validator interprets it.

Next, use binary search to find the optimal JPEG quality within the file size window. The canvas.toBlob() function takes a quality parameter that controls the file size. The file size grows roughly monotonically as the quality decreases, so binary search works well for finding the optimal quality value.

The fitJpeg function takes an encoding function, a byte window, and the number of iterations to perform. It starts by encoding the image at maximum quality. If the result is too large, it returns an error. If the result is too small, it continues the search by gradually decreasing the quality until it finds the largest file that fits within the byte window.

Some design choices include aiming for the largest file that fits rather than the first one that fits. This ensures that the photo maintains as much quality as possible while still complying with the size requirements. The algorithm checks the extremes first, and if the quality 1.0 setting is already within the byte window, it stops there. If the quality 0.3 setting is still too large, it reports that the pixel dimensions are incorrect and stops the loop.

A file that is too small can also be a real failure. For example, a mostly white photo can compress below the minimum file size even at quality 1.0. In this case, it's better to report the issue clearly rather than padding the file with extra bytes. Finally, the encoder in the browser is just a promise wrapper.