Guess Who? Board Generator

Generate custom Guess Who?-style game boards from a folder of character images. This code is based off of an idea from streamer DukTV. The program automatically determines an efficient grid layout, creates styled character cards, and places them onto a background image to produce a printable game board.

---

Requirements

• Python 3.11+
• Pillow
• uv (Astral) / pip

---

Installation

git clone https://github.com/ShafathZ/GuessWhoGameGenerator
cd GuessWhoGameGenerator

pip install -r requirements.txt             # <--- Install Programs Needed
python -u "#### NAME OF IMAGE SCRAPER ####" # <--- Collect images
# Wait for completion

NOTE: Data scrapers may get flagged by respective wiki sites and should not be used abusively. It is recommended to use your own collected folder of images instead.

---

Usage

Create a GuessWhoBoard object by providing:

• the folder containing the character images
• the background image
• the output filename

from GuessWhoBoard import GuessWhoBoard

board = GuessWhoBoard(
    input_folder="characters",
    background_image="background.jpg",
    output_file="guess_who_board.png"
)

board.generate_board()

Note: This is also included in generate.py. To run, edit the parameters in the file and then do:

python -u generate.py

Shuffle Characters

board.generate_board(shuffle=True)

The image order will be randomized before creating the board.

Generate a Random Subset

board.generate_board(subset_ratio=0.75)

The above example selects only 75% of the available images randomly. This is useful when creating multiple unique boards from a larger image collection.

---

Configurations

Several appearance settings can be customized inside the code:

self.base_cell_aspect = (4, 5)  # Character card aspect ratio
self.cell_padding = 30          # Padding on edge of character card
self.title_padding = 85         # Padding for title of the board
self.name_padding = 12          # Padding for the name inside each card
self.card_opacity = 0.75        # Opacity of card to see through to background

You can also adjust the layout scoring weights if you want a different heuristic for the boxing algorithm:

self.boxing_weights = {
    "cols": 80,                 # How much to value keeping column sizes consistent
    "aspect": 200,              # How much to value keeping aspect ratio of cards consistent
    "scale_penalty": 1200,      # How much to value keeping the image file size small (pixel count)
    "rows": 20                  # How much to value keeping the row sizes consistent
}

These values influence how the automatic layout algorithm chooses the board dimensions.

---

Layout Algorithm

The most important part of the project is automatically finding a layout that makes the board look balanced regardless of how many character images are provided. Instead of using a fixed number of rows or columns, the program evaluates many possible layouts and assigns each one a score.

1. Find # Possible Layouts

   • Find maximum card size for the given layout.
   • Calculate the required number of rows for each sub-layout.
   • Create a unique layout test for each form of card structure and card dimensions (removing padding and title space)

2. Scoring System

   • Reward larger card sizes.
   • Favor wider, more balanced grids.
   • Prefer layouts that preserve the target aspect ratio.
   • Penalize excessive rows and extremely large background scaling.

3. Select Optimal Layout

4. Resize the background to fit optimal dimensions

5. Generate the board

   • Create a styled card for each character.
   • Composite all cards onto the background to produce the final image.

---

Output

After generation, the program reports:

Board saved as guess_who_board.png
Layout: 6 columns × 5 rows
Cell size: 190×238 px

The resulting PNG can be printed or used digitally as a custom Guess Who? board.