Recently, I was happily surprised to see that split-image, a Python package I published on PyPi, has 200+ downloads per month. It’s nice to know that such a simple program, with under 100 lines of code, is helping so many developers.

split-image is a Python package that you can use from the command line to quickly split an image into grid tiles:

This is a short overview of how I developed split-image in the span of a few days, the problem it solves, and example use cases.

Why I needed to split images into tiles

The idea for developing split-image, came from the need to streamline a process I had to do fairly frequently for MapChart‘s social media.

Each time I shared a map made with MapChart on its Instagram account, I wanted to additionally post the map split into 4 zoomed-in parts. This helps with showing all the map details in the small phone screen, and also looks cool:

I also needed to first resize the image into a square, to follow Instagram’s requirements (indeed, there are a lot of apps, with subscriptions and in-app purchases, that do just that!).

It may sound like a simple thing to do, but surprisingly, I had to search a bit to find how to do it with various image processing apps I use every day. Some of the solutions I used and their required steps were:

• Photoshop:
  • Change the canvas size to square (manually).
  • Paint the newly added pixels with the map’s background color.
  • Use the Slice tool to divide the image into 4 slices (2 rows and 2 columns).
  • Use the File > Export > Save for the web (Legacy) option to finally export the image’s slices/tiles to separate images.

• IrfanView:
  • Change the canvas size to square (manually).
  • Choose the color to paint the newly added pixels with (matching the map’s background color).
  • Use Options > Export Image Tiles (split image) to save the image as multiple tiles.
• Online tools:
  • I also used various websites with image-editing tools from time to time. You could easily find these with a Google search.
  • On most of them, making the image into a square shape or expanding its background color was missing, or you had to use a different tool.
  • I also didn’t like the fact that I had to upload my images to another server, in order to complete such a small task.

Naturally, I wanted to save time and avoid all those different tools from above and their manual steps, by building my own tool for automating the process!

Development

So, this is what the tool should do:

• Take an image as input.
• Optionally resize it to a square image, and fill the added pixels with the image’s background color (if it can be determined).
• Split the image into the provided number of rows and columns.
• Export the generated image tiles with an appropriate file name.

I am sure that this can be done pretty easily with most programming languages, but I opted to use Python, for a couple of reasons:

• I am fairly proficient in Python and its ecosystem, and I like using it, especially for quick scripting.
• There are a lot of packages to handle image processing, and file I/O operations are pretty straightforward.
• Eventually, I wanted to share this with the community, in case other people find it helpful (which they do, apparently ?), and Python is one of the most popular languages.

The excellent Pillow library was enough to handle all the image processing, like reading the pixel values, resizing, etc. Probably the most interesting function of the script I wrote, is the one that determines a background color to fill the additional pixels with, when resizing the image to a square:

To do this, it checks the value of the pixels of the border areas (top, bottom, left, right) of the image, and finds the most commonly used color. It proved especially helpful for using in my specific use case, as maps usually have a specified background color.

In the end, the split.py script came to only 81 lines of code, including the ability to be used from the command line, so feel free to have a look!

From then on, it was just a matter of adjusting to PyPI’s requirements to be able to publish it.

How to use

I am a big fan of tools that do one thing and do it well.

This package has only a couple of options and can be easily used from the command line.

To install it, you should use pip:

pip install split-image

Then, you can use it from the terminal, like this:

split-image cat.png 2 2

This will split the cat.png image into 4 tiles (2 rows and 2 columns):

You can set the number of rows and columns you want. Optionally, you can also set a flag to resize it to square first:

split-image bridge.png 3 4 -s

This will split the bridge.png image in 12 tiles (3 rows and 4 columns). The --square (-s) argument will also resize the image into a square before splitting it.

The tool saves all generated images in the same directory as the original image.

Use Cases

Some use cases for split-image that I can think of:

• Splitting an image to use in a gallery for Instagram posts. This is why I developed this in the first place, as I described above.
• Making those Instagram profile grid layouts (example), that were all the rage a couple of years ago. There are already free and paid apps that do this, but split-image can surely be used as an alternative.
• Just squaring an image (example command: split-image cat.png 1 1). A quick way to avoid using another app or website for such a simple task.

Of course, I am not sure how other people are using it, as I haven’t seen it yet in the wild, even though it has been downloaded over 2,000 times already.

If you eventually try it, I would be most interested to know how it helped you!

Stats

I wasn’t aware that there is a way to see stats for PyPI packages, as PyPI doesn’t display this information in the package’s listing page.

However, I came across the PePy tool, which retrieves this data from the official BigQuery repository and displays it in a simple interface:

As of February 2021, after ~6 months of the package being available, it has over 2,500 downloads, which is pretty impressive!

Future development

Currently, I have no immediate plans for extending the package. It serves my purposes fine, and it seems to do so for other people as well.

If, of course, anyone asks for a feature or a bug fix through GitHub, I would be more than happy to work on it.

Conclusion

All things considered, split-image has been a fun, small project to work on.

I loved how easy it was to build and publish, and the fact that it proved helpful for other people than me. As with most things, a lot of us face similar issues in our daily tasks, so it’s always nice to share solutions, with the help of open-source!

If you try it, I would love to hear your thoughts!

Finally, here goes a 9-tiles split of my cat: