Package: pylettize
Any image in any colormap 🎨🐍Have you ever been in the middle of creating the ultimateaestheticset up only to find that your favorite wallpaper does not vibe with your new color scheme? Well, fret not,pylettizeis here for you. This is a simple piece of software allowing you to apply custom color palettes to any image you can think of. Need that classic Bliss™️ re-cast in Gruvbox colors? Look no further!Note:This project is still in development, without a clear release date set. It is useable at the moment, but might require a bit of hacking on your end if you want it to work exactly as you want. If you want to contribute in any way shape or form, check out the contribution guidelines below!Installation and usageThe easiest way to get started is to simply install pylettize from pip by runningpip install pylettizeAlternatively, it is possible to build from source by cloning this repository. Ideally the following steps would be done in a virtual environment with a minimumpipversion ofv22.2.2:gitclonehttps://github.com/frans-johansson/pylettize.gitcdpylettize
pipinstall-e.After installing, you should now be able to runpylettize --helpand see the general usage instructions. As an example though, to apply the defaultgruvboxpalette tocat.png(which some of you might recognize as Chelsea the cat from Scikit-Image), you would run the following command:pylettizesoftcat.pnggruvbox-oaesthetic_cat.png-T0.05which will save your output to a file calledaesthetic_cat.png. The-T 0.05option sets thetemperaturevalue for the soft blending operation. Basically, a higher value means the colors become less distinct and more "smooth", but more on this in the next section.FeaturesThepylettizeutility currently supports two main blending modes: hard and soft. These can be applied with either custom palette file by supplying the-pflag before the palette name (instead pointing to your custom palette) or to one of the followoingdefault palettes:gruvbox, based on the color scheme by morhetzobama, drawing from the colors of the hope postersprimaries, simply CMY and RGB in their purest formsThough as mentioned, any text file containing hexcolors separated by newlines can be used as a palette. Here's a (spooky 🧛) example free of charge!#44475a
#f8f8f2
#6272a4
#8be9fd
#50fa7b
#ffb86c
#ff79c6
#bd93f9
#ff5555
#f1fa8cHard blendingThe simplest kind of blending supported currently ishardblending. This simply sets each pixel in the output image to its nearest palette color in RGB space, utilizing the euclidean distance. The effect can be kind of rough and noisy, which is certainly a look you could shoot for if you want. If, however, you'd like a more smooth look: keep reading!Soft blendingThe main difference when using thesoftoption is that each pixel in the output image becomes a linear combination of several palette colors. As with the hard blending option, the euclidean distance measure in RGB space is used. However, this value is normalized and inverted to get a similarity measure instead. Then, the distribution of these similarity values across the palette colors is passed through atemperature scaled softmax transform, which can either make the distribution more or less concentrated using the-Ttemperature option. Generally speaking, and as indicated below, a higher temperature value means "smoother" colors and a lower value means more distinct colors.Temperature valueResultOriginalT=0.25T=0.1T=0.05Care should be taken when setting the temperature to low or too high though, as indicated below.Temperature valueResultT=10T=0.001Additional planned featuresTo round off this section, here are some planned features for the future of this little project.Automatic palette extraction using clustering algorithms1-to-1 palette mappings using association algorithmsA hosted, installable package on PyPI (yes, you'll be able topip installit!)More default palettes!Note that there is no clear roadmap for these features, and there is no guarantee they will in fact ever be implemented (🤷)Contribution guidelinesTo get started, make sure you have the following requirements satisfied on your machine:pip v22.2.2poetry v.1.4.1Anypython3version, but at least 3.8 is recommendedSet up a local virtual environment by runningpoetry shellthenpoetry installin the project root directory (where the pyproject.toml is). This should end up putting you in a brand new virtual environment associated with the project, and install all of its dependencies. To check if this step worked, try runningwhich pythonand verify that you get a path to some sort of "virtualenv" as output.Optionally, but highly recommended to avoid headaches when submitting PRs, is to set up pre-commit hooks withpre-commit installin the project root (where the .pre-commit-config.yaml file is). This should ensure that your PR at least has style compliant code ✨. If you'd like to be told your code is bad before commiting, feel free to set up linting in your editor of choice. We useflake8with a bunch of plugins (includingmypyandisort) to run the style checks, so ideally you'd want to useflake8locally for linting as well. In Visual Studio Code, adding the following to your settings file should suffice:{"python.linting.enabled":true,"python.linting.flake8Enabled":true,"python.formatting.provider":"black",}This will also enable you to format your code with our formatter of choiceblackin the editor.We usepytestas our testing framework. It should be set up such that you can simply runpytest.Feel free to submit PRs with any additions you'd like to see made to the project! We only ask that you stick to the coding guidelines (i.e. what flake8 tells you to do), and that you associate each PR with some Issue. If there isn't an issue yet for what you want to add, create one! Don't worry too much about how to format these, or what labels to use. Simply try to convey what it is you're looking to implement, change or fix.