README.md: add more notes

These were generated by rye, but I haven't committed the rye stuff
yet because I'm still deciding whether I want to use it, pipenv, or
poetry.

README.md

@@ -6,11 +6,34 @@ Fun proof of concept to generate random wildlife bingo cards for safaris with da
 </p>
 
 # Usage
+Once the requirements are satisfied you can generate a card. By default it generates a 4x4 grid with 16 images:
 
 ```console
 $ ./generate.py -i data/animals.csv -o out.jpg
+[INFO] Generated random sample of 32 animals...
+[INFO] > Creating thumbnail for Helmeted guineafowl...
+[INFO] Generated card with a 4x4 grid of animals...
+[INFO] Wrote out.jpg
 ```
 
+The script will download the images from Wikipedia, generate thumbnails for the sampled animals, and output a bingo card as a JPEG file.
+
+# Requirements
+Set up a Python 3.11+ virtual environment and install the requirements:
+
+```console
+$ python3 -m .venv
+$ source .venv/bin/activate
+$ pip install -r requirements.lock
+```
+
+# TODO
+
+- Credit photographers — these photos are all some variation of CC-BY so we need to give attribution
+- Add filtering by region — the metadata already exists, though perhaps needs to be adjusted
+- Refactor — perhaps needs to be more object oriented
+- Make a web frontend — I can imagine a light frontend that would shuffle the images in realtime and allow generation of a number of cards
+
 # License
 This work is licensed under the [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html).
 

generate.py

@@ -155,8 +155,8 @@ if __name__ == "__main__":
 
     # Get a random list of animal IDs. We will build a square grid using the
     # "across" parameter passed by the user.
-    logger.info(f"Generating random sample of {animals_df.shape[0]} animals...")
     animal_ids = animals_df["id"].sample(args.across * args.across)
+    logger.info(f"Generated random sample of {animals_df.shape[0]} animals...")
 
     # Slice those random animals from the dataframe
     animals_df_random = animals_df[animals_df["id"].isin(animal_ids)]
@@ -174,6 +174,7 @@ if __name__ == "__main__":
     # Join all thumbnails together in an array of x across with a padding of 2
     # pixels between each square.
     joined = pyvips.Image.arrayjoin(thumbnails, across=args.across, shim=2)
+    logger.info(f"Generated card with a {args.across}x{args.across} grid of animals...")
 
     joined.jpegsave(args.output_file, optimize_coding=True, strip=True)
     logger.info(f"Wrote {args.output_file}")

requirements-dev.lock

@@ -0,0 +1,85 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+
+-e file:.
+asttokens==2.4.1
+    # via stack-data
+black==24.2.0
+certifi==2024.2.2
+    # via requests
+cffi==1.16.0
+    # via pyvips
+charset-normalizer==3.3.2
+    # via requests
+click==8.1.7
+    # via black
+colorama==0.4.6
+    # via safari-bingo-cards
+decorator==5.1.1
+    # via ipython
+executing==2.0.1
+    # via stack-data
+idna==3.6
+    # via requests
+ipython==8.22.1
+isort==5.13.2
+jedi==0.19.1
+    # via ipython
+matplotlib-inline==0.1.6
+    # via ipython
+mypy-extensions==1.0.0
+    # via black
+numpy==1.26.4
+    # via pandas
+packaging==23.2
+    # via black
+pandas==2.2.1
+    # via safari-bingo-cards
+parso==0.8.3
+    # via jedi
+pathspec==0.12.1
+    # via black
+pexpect==4.9.0
+    # via ipython
+pkgconfig==1.5.5
+    # via pyvips
+platformdirs==4.2.0
+    # via black
+prompt-toolkit==3.0.43
+    # via ipython
+ptyprocess==0.7.0
+    # via pexpect
+pure-eval==0.2.2
+    # via stack-data
+pycparser==2.21
+    # via cffi
+pygments==2.17.2
+    # via ipython
+python-dateutil==2.8.2
+    # via pandas
+pytz==2024.1
+    # via pandas
+pyvips==2.2.2
+    # via safari-bingo-cards
+requests==2.31.0
+    # via safari-bingo-cards
+six==1.16.0
+    # via asttokens
+    # via python-dateutil
+stack-data==0.6.3
+    # via ipython
+traitlets==5.14.1
+    # via ipython
+    # via matplotlib-inline
+tzdata==2024.1
+    # via pandas
+urllib3==2.2.1
+    # via requests
+wcwidth==0.2.13
+    # via prompt-toolkit

requirements.lock

@@ -0,0 +1,42 @@
+# generated by rye
+# use `rye lock` or `rye sync` to update this lockfile
+#
+# last locked with the following flags:
+#   pre: false
+#   features: []
+#   all-features: false
+#   with-sources: false
+
+-e file:.
+certifi==2024.2.2
+    # via requests
+cffi==1.16.0
+    # via pyvips
+charset-normalizer==3.3.2
+    # via requests
+colorama==0.4.6
+    # via safari-bingo-cards
+idna==3.6
+    # via requests
+numpy==1.26.4
+    # via pandas
+pandas==2.2.1
+    # via safari-bingo-cards
+pkgconfig==1.5.5
+    # via pyvips
+pycparser==2.21
+    # via cffi
+python-dateutil==2.8.2
+    # via pandas
+pytz==2024.1
+    # via pandas
+pyvips==2.2.2
+    # via safari-bingo-cards
+requests==2.31.0
+    # via safari-bingo-cards
+six==1.16.0
+    # via python-dateutil
+tzdata==2024.1
+    # via pandas
+urllib3==2.2.1
+    # via requests