Pandora Palettizer is a tool that can be used to automatically convert textures.boo files into FULL RESOLUTION palettes!
This tool is a very important cornerstone of the Toontown Texture Restoration Project.
The idea of this project is simple.
After all model files (EGG files) and textures are built in the Pandora/Spotify repository, egg-palettize leaves behind a textures.boo file.
It is extremely difficult to build the Pandora/Spotify repository, and as of yet, a comprehensive guide does not exist. Creating such a guide is out of the scope of this project.
This file contains very important palettization data that can be used to construct full resolution palettes!
The Panda3D egg-palettize tool cannot be used to create these full resolution palettes, as changing the palette size rearranges all textures inside the palette.
Since the Pandora leak is from 2010, it does not contain all textures from the 2013 build of the game. As such, some palettes might be missing textures. If a single texture is missing from a palette group, each palette image might be in the wrong order! Those palettes need to repaired manually using Photoshop.
Don't worry: when you run the program, it will list all textures used inside a single palette image! If a palette has to be repaired, this will greatly help with the manual texture lookup times.
Important! When Pandora Palettizer is building palettes, it does two important translation steps: resizing the image to a nearby power of two, and applying a Gaussian blur on the image.
The Gaussian blur on the image is necessary, because some textures in a palette might have a very low resolution. Resizing those images many times would result in a very blocky image. Therefore, blurring is performed on those textures when resizing them to the required size. This Gaussian blur can be controlled using the --blur-amount
, or disabled even.
Resizing the image to a nearby power of two is another necessary step, required by the Panda3D engine by default.
By default, Pandora Palettizer will round to the nearest power of two. If a source image does not suffer more than 50% quality loss, it will downscale the image. However, if more than 50% quality loss is detected, then the image will be upscaled automatically.
It is possible to setup Pandora Palettizer to always upscale images, or always downscale them, using --resize-strategy upscale
and --resize-strategy downscale
, respectively.
To control the rounding threshold for rounding to the nearest power of two, use the --resize-threshold
flag. For example, to automatically upscale when a 20%
loss in original quality is detected, use --resize-threshold 1.2
. To automatically upscale when a 75%
loss is detected, or downscale otherwise, use --resize-threshold 1.75
.
- Use the
--jpg
flag to convert all palettes into JPG+RGB combo textures. - Use the
--png
flag to convert all palettes into PNG textures. - Use the
--all
flag to convert all palettes into both JPG+RGB and PNG textures. - Use the
--dump
flag to dump the .boo file into a large file calledboo.txt
. This flag is most useful for developers. - Use the
--skip-palette
flag to skip building palettes. If this flag is enabled, only stray textures will be built. - Use the
--skip-stray
flag to skip building stray images. If this flag is enabled, only palettes will be built. - Use the
--max-size
flag to set the maximum texture size. For example,--max-size 2048
will not allow textures larger than 2048x2048 to be created. This is the default maximum size. - Use the
--blur-amount
flag to set the amount of blurring used during texture resizing. When a texture is resized by Pandora Palettizer, it will be slightly blurred if necessary. Set this to 1.0 for default blurring behavior, and 0.0 to disable blurring altogether (which is faster, but yields ugly results). - Use the
--resize-strategy
flag to set the resizing strategy. This can be eitherupscale
,downscale
orround
. - Use the
--resize-threshold
flag to set the resize rounding threshold. This is a number between1.0
and2.0
. By default, this is set to1.5
, which will automatically round to the nearest power of two. - Use the
--boo
flag to specify the full path of the textures.boo file! For example:--boo textures_backup.boo
- Use the
--output
flag to specify the full path of the output directory. By default, this is thebuilt_palettes
directory. - Use the
--texture-dir
flag to set your Spotify/Pandora directory. This is the directory that contains thechar
,maps
, etc. directories.
Your Python version must be at least 3.6, but newer versions are appreciated.
Make sure you've got Panda3D installed. The newer, the better.
You must clone the repository, and install all dependencies from requirements.txt
afterwards.
git clone https://github.com/P3DCAT/PandoraPalettizer
python -m pip install --upgrade -r requirements.txt
cd PandoraPalettizer
usage: python -m palettizer.Main [-h] [--jpg] [--png] [--all] [--dump] [--skip-palette]
[--skip-stray] [--max-size MAX_SIZE]
[--blur-amount BLUR_AMOUNT]
[--resize-strategy {upscale,downscale,round}]
[--resize-threshold {[between 1.0 and 2.0]}] [--boo BOO]
[--output OUTPUT] [--texture-dir TEXTURE_DIR]
This script can be used to rebuild palettes from Pandora using the
textures.boo file.
optional arguments:
-h, --help show this help message and exit
--jpg, -j Convert palettes to JPG+RGB textures.
--png, -p Convert palettes to PNG textures.
--all, -a Convert palettes to both JPG+RGB and PNG textures.
--dump, -d Dump your textures.boo file into a boo.txt dump file.
--skip-palette, -n Skips the creation of palettes.
--skip-stray, -m Skips the creation of stray textures.
--max-size MAX_SIZE, -s MAX_SIZE
The maximum size that a palettized texture can be,
measured in pixels.
--blur-amount BLUR_AMOUNT, -x BLUR_AMOUNT
The amount of blur used during texture resizing. Set
this to 0 for no blurring. Default amount is 1.0.
--resize-strategy {upscale,downscale,round}, -r {upscale,downscale,round}
The resize strategy to use when resizing images.
Upscaling will always resize the texture to the next
power of two, while downscaling will always resize it
to the previous power of two. Rounding will use a
threshold to determine whether to downscale or
upscale, check --resize-threshold. Rounding at 50%
quality loss is the default option.
--resize-threshold {[between 1.0 and 2.0]}, -t {[between 1.0 and 2.0]}
A number between 1.0 and 2.0 that will help the
palettizer decide whether to downscale or upscale the
image. A value of 1.0 will always downscale the image,
while a value of 2.0 will always upscale it. Use the
value 1.5 to automatically upscale when the texture
would lose 50% of detail (rounding). For example, the
value 1.2 will automatically upscale to prevent losing
20% of detail.
--boo BOO, -b BOO Your textures.boo file, containing palettization data.
--output OUTPUT, -o OUTPUT
Your output folder.
--texture-dir TEXTURE_DIR, -i TEXTURE_DIR
The location of your Pandora/Spotify folder.
For example, to build all palettes and stray images from C:\Data\Spotify
, building both JPG and PNG files, from the textures.boo
file:
python -m palettizer.Main --jpg --png --texture-dir C:\Data\Spotify --boo textures.boo
To build only palettes from C:\Data\Spotify
, building only JPG files, with a maximum size of 2048x2048
and regular blurring (1.0 amount):
python -m palettizer.Main --jpg --texture-dir C:\Data\Spotify --skip-palette --max-size 2048 --blur-amount 1.0
To build only stray images from C:\Data\Spotify
, building only PNG files, while automatically upscaling when 25% quality loss is detected, downscaling otherwise:
python -m palettizer.Main --png --texture-dir C:\Data\Spotify --skip-stray --resize-strategy round --resize-threshold 1.25
To build only palettes from C:\Data\Spotify
, building only JPG files, while automatically upscaling:
python -m palettizer.Main --png --texture-dir C:\Data\Spotify --skip-stray --resize-strategy upscale
To dump the textures.boo
file into a boo.txt
file:
python -m palettizer.Main --dump --boo textures.boo
As mentioned before, Pandora does not contain all textures from the 2013 build of Toontown Online. Some palettes require repairation manually.
The Pandora/Spotify system is extremely difficult to build. You might need to procure a textures.boo file from somebody trustworthy.
You MUST run a manual optimization of all palettes after building the Pandora/Spotify repository! This will ensure that the palettes will take the same form and order as the 2010 Toontown Online palettes:
egg-palettize -af C:\Data\Spotify\maps\texture.txa --opt --all --egg
Some stray images might lose their landscapeness, depending on your resize strategy. Consider choosing another resize strategy, or fixing those textures manually.
Disyer has taken the liberty to try his own hand at compiling Spotify, as well as the palettes using Pandora Palettizer.
His textures.boo file, boo.txt dump and JPG+PNG palettized textures can be found on Google Drive.
Those textures were built with the following settings:
python -m palettizer.Main --texture-dir C:\Data\Spotify --max-size 2048 --jpg --png --resize-threshold 1.2 --resize-strategy round
This tool was created by Disyer, with the hope that others will be able to contribute to the Toontown Texture Restoration Project.
Many thanks to satire6 for releasing the Spotify repository in the first place! Without satire6, this tool would have never been made.