Skip to content

Get the card game

Introduction

The project is hosted on a Git repository and is publicly available at the following address: The Physics on Infinity Canvas

This repository contains all the files and resources needed to build and contribute to the project.

The project has the following structure:

.
├── .vscode # Configuration files for Visual Studio Code
├── cards-fr # Description of the cards in French
├── cards-en # Description of the cards in English
├── illustrations # Directory containing language-independent illustrations for the different themes of the cards
│   ├── kind-electromagnetism-scale
│   ├── kind-information
│   ├── kind-open-question
│   ├── kind-science
│   ├── kind-science-fiction
│   ├── kind-scientific-instrument
│   ├── kind-scientist
│   ├── kind-technology
│   └── kind-universe-scale
├── illustrations-original # Directory containing original illustrations used to create the illustrations on the cards
├── illustrations-tikz # Directory containing the TikZ source code to generate certain illustrations of the cards upstream of the card preparation
├── inputs # Directory containing icons and LaTeX configuration style files
├── join-masters # Directory containing LaTeX files to assemble the cards: printing, language comparisons, etc.
├── src # Useful Python scripts to generate the cards in different formats and generate derived card formats
├── .gitignore
├── main-cards-for-creation.tex # Master file to create the cards: quick compilation of the cards
├── main-cards-to-printer.tex # Master file to prepare the cards in their final format: final appearance of the cards with layout guide lines
├── script-cards-to-printer-fullGame.tex # Master file to prepare the cards for the "fullGame" set
├── script-cards-to-printer-quizGame.tex # Master file to prepare the cards for the "quizGame" set
├── script-install.sh
└── switch-language.sh

Prerequisites to build the project

  • A recent TeX installation (TeX Live), preferably the current year's version. The compilation uses fairly recent packages.

  • A python installation (version 3) with the pypdf library. You may need to create a python virtual environment in the src/ folder.

  • The gnuplot software is used to generate some illustrations.

  • The ImageMagick software is used by a python script to generate bitmap versions of the cards (optional).

  • An image editing software if you create illustrations (optional).

Building the project

To build the project, follow these steps:

1. Clone the repository using the command:

git clone https://gitlab.in2p3.fr/infinitycanvas/infinity-canvas.git

2. Go to the project directory:

cd [Insert the project directory name here]

3. You must select the language you want to use for the project. The available languages for now are:

  • English (en)

  • French (fr)

To change the language, you can use the following python script by specifying the desired language:

cd src/
python switch-language.py --lang=[en|fr]

The python script prepares working folders in the root of the project.

It is not necessary to run one of these scripts every time you build the project, as the language parameter is saved in a configuration file (input/version-cards.tex). If you want to change the language, you must run one of these scripts again or directly modify this file.

If no argument is provided for the shell script, it will try to detect the operating system language. If the detected language is not supported, it will default to English.

The master file main-cards-for-creation.tex is designed to work on the card texts: the formatting is minimal, allowing for relatively fast compilation and thus faster production.

The master file main-cards-to-printer.tex provides card formatting, with lines (red dotted lines) to show the frames of the elements. Any overflow can thus be detected and corrected.

4. Building the cards requires several steps.

All steps can be executed by a single script:

cd src/
python build-project.py --lang=xx [--illustrations=[true|false]] [--to-printer-files=[true|false]] [--crop-versions=[true|false]]

where xx is one of the languages given in the AVAILABLE_LANGS variable of the file src/configuration.py. This script generates all the card content in the language xx using the script create-pdf-files-cards.py.

  • The --illustrations option (default true) allows you to generate TikZ illustrations in the language using the script create-tikz-illustrations.py.

  • The --to-printer-files option (default true) allows you to create files ready to be used for printing, using the script create-pdf-files-print.py.

  • The --crop-versions option (default true) allows you to create pdf versions of the cards without margins and print marks, using the script create-pdf-crop-cards.py.

The files generated by these scripts are grouped into subfolders of a _cards-production-xx folder.

Warning, this script takes several hours to produce all the files.

Here are the steps followed by this script, which can be run one after the other.

Generation of illustrations produced by TikZ.

cd src/
python create-tikz-illustrations.py --lang=[en|fr|all] [--move[true|false]] [--picture name-of-illustration-1 name-of-illustration-2 …]

  • The --lang option allows you to generate illustrations in a specific language or for all languages (all option).

  • The --move option defaults to false. In this case, the script produces the pdf files of the illustrations, renames them correctly (with the names used in the card creation calls) and groups them in the illustrations-tikz/_PRODUCED-IMAGES folder. With the value true, the script also copies these files into the folders used for card creation.

By default, the script prepares all images. If a list of illustration names (folder name, which is also the name of the tex file) is provided with the --picture option, the script only generates these illustrations. This allows you to quickly update one or more illustrations without having to recompose everything.

Some illustrations require the gnuplot software, which must be installed beforehand.

The file illustrations-tikz/_data.json contains the creation configurations for the illustrations: LaTeX engine used (pdflatex or xelatex), use of gnuplot or not, number of illustrations to produce, destination folder for card creation. This file should only be modified if a new illustration is added or if a major change is made to a tex file for creating an illustration.

Once the illustrations produced by TikZ are ready, card creation is possible if the pdf files are correctly placed in the call folders (automatic with the option --move=true).

Building the pdf files of the cards.

cd src/
python create-pdf-files-cards.py --lang=[en|fr]

This script creates the folders containing the produced files: these folders are named according to the language. The script launches the necessary LaTeX compilations to create the pdf files for the front and back of the cards, with their margins and cutting marks.

Building files for printing.

cd src/
python create-pdf-files-print.py --lang=[en|fr]

This script creates input files and compiles LaTeX files in the join-masters folder to create pdf files ready to be printed double-sided. These files present the cards in different layouts (one or more cards per page).

Optional step: other output formats.

cd src/
python create-pdf-crop-cards.py --lang=[en|fr]

This script allows you to create pdf files of the card contents (front and back) without cutting margins.

cd src/
python create-bitmap-cards.py --lang en fr --conversion aaa bbb

This script allows you to create bitmap versions of the cards for the languages and conversion types (see PIXEL_CONVERTIONS in configuration_bitmap.py)

The script src/create-pdf-crop-cards.py uses the pypdf library, which must be installed beforehand. You may need to create a python virtual environment in src/. The script src/create-bitmap-cards.py uses ImageMagick, which must be installed separately. The file src/config_local_template.py should be used to create a src/config_local.py file configuring the path to the magick executable.

The file src/configuration.py contains various configurations for these python scripts.

How to contribute

Contributing to the project is simple. Follow these steps:

1. Fork the repository
Start by forking the repository to your own Git account. This allows you to make changes without affecting the main project. By forking the repository, you agree to abide by the project's license agreement.

2. Make your changes
After forking, clone your forked repository to your local machine:

git clone [Insert the URL of your forked repository here]

3. Make the necessary changes to the codebase.

4. Commit your changes
Once your changes are complete, commit them to your forked repository:

git add .
git commit -m "Describe your changes here"
git push origin [Insert the branch name here]

5. Submit a Merge Request
Submit a merge (pull) request to the main repository. Make sure your merge request includes a clear description of the changes made and why they are needed.

Add new languages

To add a new language to the project, follow these steps:

1. Fork the repository
Start by forking the repository to your own Git account. This allows you to make changes without affecting the main project. By forking the repository, you agree to abide by the project's license agreement.

2. Card content translation process

Edit the file src/AI-prompt-example.txt to ask the AI to translate into the target language. From this modified text, create a file data/AI-prompt-ss-xx.txt where ss is the source language and xx is the target language (two-letter codes). Then run the python script:

cd src/
python prepare-translation.py --lang-source=ss --lang-target=xx

The choice of source language is free. It is preferable to use English as AIs are well trained to translate from English. The python script creates the necessary folders for the translation process and the final destination folder cards-xx. No script will modify what is in cards-xx, to preserve any human modification made there. It is therefore possible to run the translation process several times without losing work already done in cards-xx.

The folder _translation-process/1-to-be-translated contains txt files for each card. These files can be provided directly to an AI: they contain the prompt defined in data/AI-prompt-ss-xx.txt and the content of the current card in the format described by the prompt.

Once the AI has produced the translations, each translation must be saved in the folder _translation-process/2-translated-texts with the original names.

Once these files are produced, run the script:

cd src/
python create-cards-files-from-translation.py

which will produce in the folder _translation-process/3-cards-after-translation the LaTeX files for card production. To use these files, copy them into the cards-xx folder (the script will not do this, in case old files already exist in cards-xx).

You must also create in cards-xx a copy of a localized-strings.tex file (to be taken from cards-ss). This file must be modified for language xx: babel package option, siunitx package options, addition of LaTeX macros specific to language xx if necessary, texts to describe the card types. An important point concerns the names of the card types (macros \typeText____) as well as the names of the science card packs (macros \typePack____) because these names will appear on the cards. The length of these names can affect the rendering of the cards.

You must add the new language xx to the scripts. Edit the switch-language.sh script to include the new language option. Add a case for the new language in the script to handle the language switch correctly. For the python scripts for card and illustration creation, update the AVAILABLE_LANGS variable in src/configuration.py.

Once these files are in place in cards-xx, it is possible to compile the cards with the master files main-cards-for-creation.tex and main-cards-to-printer.tex. The translation provided by an AI is not always optimal in terms of text size on the cards and vocabulary used. The translator will therefore need to work on each card to improve the translation.

The \linkWithCard command is used to structure logical links between cards. The first argument is a list of target card labels. The second argument is a text that is inserted into the surrounding text. This text must be carefully checked by the translator, as it should best mention the keywords used in the titles of the target cards. After each compilation, at the end of the pdf of the master file main-cards-to-printer.tex, the translator will find, for each target card, a list of these texts used in source cards. Their task is to standardize these texts as much as possible with the title of the target card. This is important because workshop participants will use these texts to identify the links between the cards themselves. It is therefore a very structuring element of the workshop.

The translation does not take into account the date data of the cards, nor does it modify the illustration calls that depend on the language (suffix _xx in the name of some illustrations). The translator will therefore need to manually modify these dates and create the translated illustrations.

3. Illustration translation process

Since the illustration file calls are not automatically modified, compiling the cards with the files produced so far will work, but with the illustrations from language ss. This allows you to translate the illustrations one by one without blocking production tests.

All illustration files used to create the cards are in subfolders of illustrations. So you need to look there to see what needs translation.

The illustrations to be translated are produced in TikZ. The translation procedure for these illustrations is planned and takes place in the illustrations-tikz folder. Each illustration is produced by a LaTeX file in a specific folder (the folder and tex file names must be the same). The COMMONS folder contains illustration text files named common-texts-ss.tex. You need to translate the contents of the macros defined in this file and create a common-texts-xx.tex file. Some illustrations have a language file in their own folder, mosaic-universe-scale and periodic-table-elements, which must also be renamed and translated. The creation of illustrations in TikZ was described above.

4. Build and test Generate the card game in the new language to ensure everything works correctly.

5. Commit your changes Once your changes are complete, commit them to your forked repository:

git add .
git commit -m "Add support for [New language]"
git push origin [Insert the branch name here]

6. Submit a Merge Request Submit a merge (pull) request to the main repository. Make sure your merge request includes a clear description of the changes made and why they are needed.

Python scripts

List of python scripts and their functionalities. All these files are in the src folder.

Configuration tools

configuration.py

is a configuration file: possible languages, game formats, folders, and various other variables to create the different elements. The AVAILABLE_LANGS variable contains the available languages.

configuration_bitmap.py

is a specific configuration file to describe how to produce bitmap images from pdf files. The essential variable is the PIXEL_CONVERTIONS array whose keys are used by the bitmap version production script.

config_local_template.py

is a file that allows you to create a config_local.py configuration file to designate the path to the ImageMagick magick executable. If this file does not exist, by default the path is "magick", which means the command must be directly accessible by python.

utilities

utils.py

is a file containing functions used in the python scripts.

python switch-language.py --lang=xx

where xx is one of the languages given in AVAILABLE_LANGS. This script installs the language xx for direct compilation of the LaTeX master files and creates a set of language-specific folders.

python create-tikz-illustrations.py --lang=[xx|all] [--move=[true|false]] [--picture picture-name-1 picture-name-2 …]

where xx is an available language in AVAILABLE_LANGS, --move (optional, default false) allows you to move the produced illustrations into the folders used to produce the cards, --picture (optional) allows you to produce only the given illustrations. This script produces the TikZ illustrations in the selected language xx or in all languages with the language option all. The files are grouped in the illustrations-tikz/_PRODUCED-IMAGES folder.

python prepare-translation.py --lang-source=ss --lang-target=xx

where ss is an available language in AVAILABLE_LANGS and xx a new language. This script prepares the files to create a new version of the cards in language xx from language ss. The process is described above.

python create-cards-files-from-translation.py

This script generates the LaTeX files of the cards in the language translated via an AI and in the format given by the script prepare-translation.py. The process is described above.

Building the project

python build-project.py --lang=xx [--illustrations=[true|false]] [--to-printer-files=[true|false]] [--crop-versions=[true|false]] [--labels label-cards-1 label-cards-2 …]

where xx is one of the languages given in AVAILABLE_LANGS. This script generates all the card content in the language xx (using the script create-pdf-files-cards.py).

  • The [true|false] options allow you to generate TikZ illustrations in the language (--illustrations, which uses the script create-tikz-illustrations.py, default value true), to create files ready to be used for printing (--to-printer-files, which uses the script create-pdf-files-print.py, default value true) and pdf versions of the cards without margins and print marks (--crop-versions, which uses the script create-pdf-crop-cards.py, default value true).

  • The --labels option (optional) allows you to specify card labels to produce, and only those. The files generated by these scripts are grouped into subfolders of a _cards-production-xx folder.

python create-bitmap-cards.py --lang xx yy … --conversion aaa bbb …

where xx, yy, etc. are available languages in AVAILABLE_LANGS and aaa, bbb, etc. are bitmap conversion type keys available in PIXEL_CONVERTIONS (see above). Warning, the cards in pdf version in the selected languages must exist before running this script. This script generates bitmap versions of the cards in the chosen languages and in the formats selected by the --conversion option. These files are stored in subfolders of _cards-production-xx.

python create-pdf-comparison.py --langL=xx --langR=yy

where xx, yy, etc. are available languages in AVAILABLE_LANGS. Warning, the cards in pdf version in the selected languages must exist before running this script. This script produces a pdf file to present side by side on each page the front and back of the cards in the selected languages (left and right). The created pdf file cards-lang-comparison-2.pdf is located in the join-masters folder.

python create-pdf-crop-cards.py --lang=xx

where xx is an available language in AVAILABLE_LANGS. Warning, the cards in pdf version in the selected language must exist before running this script. This script produces pdf versions of the cards without margin or print marks. The files are in a subfolder of _cards-production-xx.

python create-pdf-files-cards.py --lang=xx [--labels label-cards-1 label-cards-2 …] [--games=[all|fullGame|quizGame]] [--sets set_one set_two …]

where xx is a language available in AVAILABLE_LANGS.

  • --labels (optional) allows specifying card labels to produce, and only those (without this option, all cards are produced),

  • --games allows specifying the game to compose (without this option or with all, all games are composed),

  • --sets allows specifying the sets of cards to compose (without the option, all card sets are composed; see the CARD_SETS variable in configuration.py).

This script generates the cards in PDF format for the chosen language and given options. The cards are produced in subfolders of the _cards-production-xx folder. Before generating the card PDFs, the script clears the production folders. However, if labels are provided or a partial list of card sets is supplied, the script does not delete already generated cards: it considers this a partial update of the card PDFs. To produce all cards for all games, it is recommended to use build-project.py, which runs this script and uses the same --labels option.

python create-pdf-files-print.py --lang=xx

where xx is an available language in AVAILABLE_LANGS. This script produces pdf files grouping the cards in different ways, in order to print them in different formats. The cards are produced in the cards-pdf-print subfolder of the _cards-production-xx folder.