This is a set of 100% unnecessary advanced user tools for Shmeppy.com. There's no need to mess with these if you're just starting with the platform.
Completely unaffilliated with the Shmeppy minimalist virtual tabletop application - Just built by a user for personal use and other users.
Many thanks to John Sullivan for their awesome, thoughtfully designed and (currently) free!?! product.
More info on Shmeppy here: https://shmeppy.com/about
Please don't pester John with any questions on this tool, they didn't ask for, make or maintain it.
Main documentation: docs/imageconverter.md
Images -> Maps
Works with image files to convert to .json files suitable for import into Shmeppy or use with the maptools module (below).
Three main methods for processing image, see /docs/ for details.
Main documentation: docs/maptools.md
Map(s) -> Map
Creates a single Shmeppy .json map file from two (or more) other Shmeppy .json map files.
Map(s) -> Map(s)
Fetches all tokens from a .json map file, and creates an output .json map file with all tokens grouped together (excludes the edges/fills).
To use, you have two options:
Download as a zip (or clone with Git), extract and run from a command line:
python ./shmeppytools <*file_path(s)>
- The images or mapfiles (
.json) can also be specified later from an input prompt. - Multiple map files (
.json) can be specified via command line if using the merge maps or fetch tokens features. - Will likely need to install additional packages (see detailed instructions below)
For a stand-alone application (with less functionality) see the /build/ folder. The .zip and .exe files should work by themselves without installing Python. The .exe files are self-contained, whereas the .zip contains a .exe but contains multiple separate files which some users may find confusing. The .zip packages will run more quickly and contains bundled README files.
See build/README.md for more info.
See /docs/ for information on using these tools.
- Navigate to main project directory.
- Run the script using:
python ./shmeppytools <*image_file_path>
or
./Image_to_Shmeppy_JSON_v2.2.1.exe <*image_file_path>
(depending on which file you have)
- The image can also be specified later from an input prompt.
- Will likely need to install additional packages (see detailed instructions below)
-
After a possible prompt to provide an input file, you will see prompts to specify the processing method, and the map dimensions.
-
The maximum map dimension sets the scale of the Shmeppy map - typically one 5x5 ft map square = one Shmeppy tile, but some players use a different scale (e.g. one map square equal to 2x2 Shmeppy tiles).
-
Locate the output map in the current working directory.
-
Import the
.jsonfile into Shmeppy using theGames >>sidepanel in the upper left.
Note: This script will only generate a map using 'fill' - not any 'edges'
- Navigate to main project directory.
- Run the script using:
python ./shmeppytools/maptools <map_path_1> <map_path_2>...<map_path_n>
or
./map_combiner_v0.2.3.exe <*image_file_path>
(depending on which file you have)
- The maps can also be specified later from an input prompt.
- Uses standard python packages
- Minimum spacing between maps can be specified through a prompt.
- This function can also be accessed via the main menu (
python ./shmeppytools/maptools) but may require installation of additional python packages if done so.
No need to install python, but you'll be limited to when specific builds are created.
- In /build download Image_to_Shmeppy_JSON_v2.x.x.zip
- Extract
- (optional) place image file in
Image_to_Shmeppy_JSON_v2.x.xorImage_to_Shmeppy_JSON_v2.x.x\Maps - Run
Image_to_Shmeppy_JSON_v2.x.x.exefrom within Image_to_Shmeppy_JSON_v2.x.x folder. - Output map will be in the current working directory.
You will be prompted to supply the path of an input image, or can provide it directly from a command line:
Image_to_Shmeppy_JSON_v2.x.x.exe <*image_file_path>
If you're new to command line usage, you can usually type just a few letter of a filename then hit Tab to autocomplete.
Also, the arrow keys ↑or↓ will let you cycle through recent entries, which makes repeat operations (with different settings) a bit easier.
Installing python will provide the most reliable use of this tool, as well as allow you to access the most recent updates to the script.
You'll need a Python interpreter - this is basically a program that lets you run scripts/programs written in the programming language of Python.
Guide here: https://wiki.python.org/moin/BeginnersGuide/Download
(or plenty of other guides if you google "Installing Python for Windows/Linux/Etc")
Oh, tons of ways to do this. Click on the green Code ▼ button toward the upper right, click "download zip". Unzip folder someplace convenient on your computer (we'll assume your desktop).
Upgrade or install Pip the package manager. It comes standard if you used the python install link above.
Python includes a strong standard library, but this program uses a few additional packages you may not have installed:
haishoku
cutie
Pillow (commonly included with Python interpreters)
A full list of packages and their purposes can be found at the bottom of this document.
open a command line and run:
python -m pip install -r requirements.txt
You can see all installed packages by using the following commands in a terminal (see next section if you need help):
pip list or python -m pip list
Install a package using:
pip install <package name> or python -m pip install <package name>
For example:
python -m pip install haishoku cutie Pillow
Package names are case sensitive.
Linux: If you use Linux you probably know how already.
Windows: Win + x, followed by i to open Windows PowerShell
Having trouble? More ways to access PowerShell
In the terminal window, navigate to the folder where you saved both the script and your image file. For example, if you were using Windows and saved both on your desktop the command would be:
cd desktop\ShmeppyImagetoJSON or
cd C:\users\<your_username>\desktop\ShmeppyImagetoJSON
Call the script by entering the following command:
python shmeppytools
You will be prompted to enter the path for the image file. If it's in the \ShmeppyImagetoJSON\ folder, just enter the file name, including the file extension. (e.g. example_file.jpg)
You will then see prompts to specify the processing method, and the map dimensions.
The maximum map dimension sets the scale of the Shmeppy map - typically one 5x5 ft map square = one Shmeppy tile, but some players use a different scale (e.g. one map square equal to 2x2 Shmeppy tiles).
The map file will named something like <image_name>_<width>x<height>_2020... and current working directory. The console should also have an line describing where the file was saved.
Navigate to Shmeppy.com, click on the Games >> button in the upper right. At the bottom of the side panel, click on Import Backup and select the file you created earlier with the script.
Import the .json file into Shmeppy using the Games >> sidepanel in the upper left.
Note: This script will only generate a map using 'fill' - not any 'edges'
Don't bug John! But feel free to bug me, or jump on the discord and try asking there: https://shmeppy.com/help-and-community
The last time I did serious programming was on a Commodore64 (or feels like it at least). Feel free to send a message if you're having any issues.
json (for exporting the map)
datetime (used for map file names)
pathlib (to aid in compatibility across different operating systems)
sys (system stuff like take command line arguments and exit the program)
haishoku (palette related functions)
Pillow (also known as PIL, used for general image processing)
cutie (user input menu)
For reference, build using these versions of the non-standard packages:
haishoku == 1.1.8
cutie == 0.2.2
Pillow == 7.2.0
V1 basic BOX and NEAREST filter/resize processing
V2 Palette processing and additional filters
V2.2 Palette sampling introduced
V2.3 Map combiner and Fetch Tokens integrated