Speculative Köppen-Geiger Climate Classifier (skcc.py) (c) 2018-2020 Patrick Harvey and other contributors [see the included LICENSE.txt and CONTRIBUTORS.txt] skcc is a simple command-line tool intended for automating the process of using input temperature and precipitation data in image form to classify regions according to the Köppen-Geiger climate classification system (or other systems). It is aimed at speculative or fictional worlds and is designed to work with input data formatted in a way that is more feasible for creation by analysis or fiat rather than empirical measurement. As such, it is not strictly accurate to the climate classification system, as the input model does not support this; however, the goal is that it produces a reasonable approximation. SETUP / DEPENDENCIES skcc.py requires Python 3, with Pillow (https://github.com/python-pillow/Pillow) installed. USAGE The input data should take the form of four images of equal dimensions in RGB format (they may include alpha channels, but these and any other channels beyond RGB color channels will be ignored). These images should represent temperature and precipitation for each of a winter extreme month and summer extreme month, respectively. These should be represented by the colors in the image - temperatures and precipitations should be colored according to a category, wherein temperatures and precipitations of a particular color will all be grouped together and assigned one value, which typically should be the average for the temperature or precipitation band the category represents. skcc should support multiple input file formats, although given the necessary color precision lossless formats are recommended. skcc has been tested exclusively using .png files. What colors represent what temperature/precipitation bands, as well as what color represents ocean, can be determined by providing input profiles as additional inputs, which map input RGB colors to temperature/precipitation averages. Temperature and precipitation use separate input color profiles; these are optional arguments for use if your input images do not match the default color categories used by skcc. Custom input color profiles can have more or fewer distinct temperature/precipitation bands than skcc uses by default. Finally, when run skcc will take this input data and write to the provided output file name an image of identical dimensions to the input images, colored by Köppen-Geiger climate category. An output color profile can optionally be provided to determine what colors will be used as output for what climate categories. The file extension should be included in the output filename. Larger image sizes can take a bit of time to be processed (testing on ~4400x2200-pixel input images took approximately 20 seconds to complete). Invoking skcc.py should generally appear as follows: python ./skcc.py --tempns="JulTemp.png" --tempnw="JanTemp.png" --precns="JulPrecip.png" --precnw="JanPrecip.png" --outfile="output.png" In particular, note that --tempns corresponds to the northern-hemisphere summer temperature, and --precns the north-hemisphere summer precipitation. Likewise, --tempnw is for the northern-hemisphere winter temperature and --precnw the northern-hemisphere winter precipitation. The filenames in the example should be replaced with actual filepaths to the input images. All of the arguments shown above are required to run the script. The format of the output image depends on the extension given in the outfile name. The additional options for defining custom input and output color profiles are as follows, and are optional: --tempprof="defaultTempProfile" Defines "defaultTempProfile" as the filename from which to load the temperature input color profile --precprof="defaultPrecProfile" Defines "defaultPrecProfile" as the filename from which to load the precipitation input color profile --outprof="defaultOutputProfile" Defines "defaultOutputProfile" as the filename from which to load the output color profile The proper format for the input and output color profile files can be seen in the included default files, which also contain explanations on how to construct custom versions of these. These files also describe the defaults used by skcc.py if no custom color profile is specified for any of the input/output categories. Another command-line flag allows you to set the script's operational mode. If not specified, it will default to performing Köppen-Geiger climate classification as its normal usage. The mode flag can also be used to perform Holdridge Life Zone category classification instead, by being specified as follows: --mode=holdridge Any value passed to the --mode flag that is not a valid mode will result in an error. Valid modes consist of 'koppen' or 'holdridge'. There is also a --debug command-line flag, with no arguments. If present, error output will be more verbose (it will include the Python stack trace of the error). It's mostly of interest for debugging purposes. The final optional command-line flag is --quiet. This disables the text output on completion ('Output climate map to...'). Note that error messages are not disabled by this flag. Note that the invocation of Python in the command line can depend on your installation. Defaults for different versions of python have used 'python', 'py', etc.. Run Python on the command line using whatever identifier is correct to your installation. HOLDRIDGE MODE The script can also perform classification of Holdridge Life Zones, as opposed to Köppen-Geiger climate classification. As noted above this can be enabled by passing '--mode=holdridge' with the other command-line arguments. The rules for inputs, and how custom colors can be defined, are the same - summer/winter maps of temperature and precipitation are passed in and custom color profiles can optionally be used as opposed to the script's defaults (the default input profiles are the same for Köppen-Geiger and Holdridge classification). Output profiles must cover the Holdridge Life Zone categories instead of Köppen-Geiger climate classes. The included 'holdridgeDefaultOutputProfile' is a sample custom output profile for Holdridge classification, and matches the default output colors used by the script if no custom output profile is specified. The default color profile lumps numerous Holdridge zone types together; custom options could define significantly more detailed output by giving different colors to some of the categories that are assigned the same colors in the default configuration. In this mode the classifier extrapolates an average biotemperature for each pixel from the two extremes, assuming a sinusoidal interpolation between those values for intervening months which are then clamped to the range [0, 30] degrees Celsius before averaging over the year. Annual precipitation is approximated by a simple (summer month * 6) + (winter month * 6) from the two input precipitations. The classifier uses 17 degrees Celsius as the 'critical temperature line' for differentiating 'warm temperate' life zones from 'subtropical' ones. Holdridge mode takes slightly (estimated approx. 20%-25%) longer to run than the default Köppen classification mode. This is because the biotemperature computation is somewhat more computational work-per-pixel than that performed by the Köppen classifier. COLOR CORRECTION SCRIPT The script correct_colors.py by CTA, included in the repository, is intended to produce an input image from an existing input image with colors corrected to match a specific input profile. This is particularly useful if an input image was produced with anti-aliased drawing tools by accident, producing a large number of pixels with invalid colors along the borders of regions on the map. The script will produce an image that is a duplicate of the provided input, except that pixels whose colors do not match the input profile will be recolored to match the "closest" valid RGB color in the profile. The command-line arguments to this script include "input_img", which should be set to the path of the input image to produce a color-corrected version of. Likewise, "output_img" should be set to the desired path for the corrected version. The argument "colors" should be set to the input profile to correct the image to valid colors for. The "--wrap" argument can be set to x or y to state which axis should be considered longitude for the input image, to ensure correct behavior by the script around the poles. Note that this script does not support input profiles that include a default value for non-matched colors (since all colors are valid for such profiles). Running the color correction script requires the additional Python package NumPy (see https://numpy.org) to be installed in order to run. NOTES ON KNOWN WEAKNESSES The input model takes temperature and precipitation only for two extreme months of the year, which is more readily feasible to be hand-generated than twelve individual months. However, this means a precise classification for Cb/Cc and Db/Dc climate categories according to the Köppen-Geiger system cannot be done precisely by the definitions, and the output can be a bit inexact as a result regarding these particular category distinctions. Additionally, this input model means that (for example) regions whose annual precipitations are not well described via extrapolation by the mean of two annual extremes - or where precipitation and temperature extremes do not coincide temporally - can be misrepresented. As skcc.py is intended for classification on fictional worlds this can be less problematic than it is in trying to replicate real-world results based on real-world data, but these are particular notable cases and should be kept in mind. For Holdridge mode, the script attempts to extrapolate temperature values and annual rainfall total from the given summer/winter extreme month values, which can introduce error. In particular, areas with very dry or very wet extremes may be assessed as drier or wetter than they might realistically be if they were to be measured throughout a year. Again, the goal of this is to keep input relatively manageable to produce by hand or fiat, as a full set of twelve month's data might not be. TROUBLESHOOTING In response to error messages: "ImportError: No module named PIL" --> A Python error message generated when Pillow (see dependencies section above) is not installed or could not be found. Make sure the script is being run with Python 3 as well as opposed to a 2.x or other version. "Error: One or more required input data files were not specified." --> Indicates that one or more of the two temperature input files and the two precipitation input files were not specified on the command line. The script requires that all four of these inputs are provided in order to function. "Error: No output filename specified." --> Indicates that no filename was specified on the command line to output the resulting climate map to. Specify one using the --outfile= flag. "Error: Invalid line in output profile: <text of line>" --> Indicates that the shown line in a custom output profile was invalid. Check the defaultOutputProfile for an explanation of the format that output profiles should take. "Error: Invalid line in input profile: <text of line>" --> Indicates that the shown line in a custom input profile was invalid. Check the defaultTempProfile and defaultPrecProfile files for explanations of the input profile format. "Error: Could not open <input|output> profile: <filename>" --> Indicates that the input or output profile shown could not be opened. Check to make sure the filepath that was provided on the command line is correct. "Error: Invalid <temperature|precipitation> map color value: (<R>,<G>,<B>)" --> Indicates that an input temperature or precipitation map contained pixels of a color that does not match any color in the input temperature or precipitation color profile in use. If no --tempprof or --precprof flags were specified, the script will be using the same profile as that indicated in defaultTempProfile and defaultPrecProfile respectively. If custom profiles were provided, the script will be using these. This error can commonly be caused by having used antialiased drawing tools in creating the input maps - all the colors used must be pixel-exact, so avoid 'paintbrush' type tools and the like for constructing the input maps. If custom profiles were used, also check to make sure that these profiles specify the same RGB colors used in the input maps of the corresponding type. Ideally you should ensure only valid colors are used in your input images, to ensure expected results; however the color correction script (see above) can also be used to automate correcting "off" colors such as those that might be produced by anti-aliased drawing tools. ACKNOWLEDGEMENTS The general classification process used by skcc.py is drawn from work by users Azélor and Charerg of the Cartographer's Guild (www.cartographersguild.com). The widely-used Köppen-Geiger climate classification was originally published: Köppen, W., 1884: 'Die Wärmezonen der Erde, nach der Dauer der heissen, gemässigten und kalten Zeit und nach der Wirkung der Wärme auf die organische Welt betrachtet' The particular version of the climate classification on which skcc.py is based on that described in: Kottek, M.; Grieser, J.; Beck, C.; Rudolf, B.; Rubel, F., 2006: 'World Map of the Köppen-Geiger climate classification updated' Holdridge Life Zones were originally defined by: Holdridge, L.R., 1947: 'Determinations of world plant formations from simple climatic data'. Science vol. 105, is. 2727, p.367-36\ 8.