Creating a Card Deck
Cardographer Platform, 2021-12-09, version 1
You need to have registered with the cardographer platform website and be logged in.
Navigate to the Decks tab.
Click “New Deck” and you should see a list of available “template” decks that you can copy:
Click the deck that you want to copy as a starting point, but note:
- “Databox” is an example deck of cards with a title, icon, description text and category (name and icon) (example below)
- “Blank Deck” has no predefined deck attributes/columns and no initial build files which will need quite a lot more work to start building cards with.
- Other decks have probably been created by other site users and may or may not work!
Once a new deck has been created, or selecting an existing deck from the Decks tab, will show (initially) the Details tab for that particular deck. Note the deck name just below the tabs.
The checkboxes at the bottom are used to set the state of the deck:
- “Usable” – the deck is nominally ready to use, and, for example, will appear in the deck list offered in the Session decks view.
- “Public” – deck will be available to other site users.
- “Locked” – changes to cards should be prevented.
- “Template” – deck is available to make a copy from (in Create Deck), but may NOT be available to use as a regular deck.
- “Disable re-build” – rebuilding card images should be prevented.
Don’t forget to “Save” if you make any changes.
Clicking on the revision name and chooser (grey text to the right of the deck name in the tab bar, e.g. “v1 initial” in the figure above) will show the “revisions” that exist for the current deck. There is always one initial revision:
A Revision is a version of the cards. Normally you would have one revision for each published or widely used version of a deck of cards. Normally you would only be making changes to the most recent revision, and older revisions would be “Locked” and “Disable re-build” so that they can’t be changed by accident.
“+ New Revision” creates a new revision of the deck that can be edited without affecting any other revision of the deck.
“Delete Deck” will delete the entire deck including all of its revisions. You should never normally delete a deck that has been used in anger!
The Cards tab for a specific deck (and revision) lists the cards currently in the deck.
Currently cards are always specified and edited via a CSV (Comma-Separated Value) file, which is a kind of spreadsheet file that can be exported from Excel and similar applications.
“Download CSV” will download a CSV file which contains all of the information in the system about the cards in the current deck. If you created a deck using “Create Blank Deck” then there are no spreadsheet columns defined and this option will not be available until you upload some initial definitions.
“Upload CSV” will allow you to choose a local CSV file, upload it, and use the information in it to update/replace all of the cards in the current deck.
A basic CSV file to start with would be like the following:
title:,id,name,description,category,back
export:,Y,Y,Y,Y,Y
card:,tutorial_basic_fish,Fish,Some fish,Basic,basic
You should find some more examples in github.
The column definitions are below. There is one card defined in this example, "Fish".
If you upload this file and download it again you will see additional
use:, description: and default: rows.
In most CSV files (including these) the values in the first row are the names of the columns, and specify what values in those columns mean.
The special value “title:” in the first column tells cardographer that this is a special format spreadsheet in which the first column values specify what each row is for. These row “types” are:
- “title:”, the first row containing the names of the columns
- “use:”, which gives cardographer a hint about what each column means (see below)
- “description:”, optional explanation for each column
- “export:”, should normally be “Y”, so that the values in that column are “exported” to the card building process
- “default:”, any default values for that column; not current used/useful.
- “card:”, a row which specifies one card
Note, if you don't include "use:" initially then cardographer uses the "title:" value to guess the use, so using the following as titles is also a good idea...
There are a few important values you may need in the “use:” row:
- “id”, a unique identifier for each card, which should normally be a string without spaces in the format “DECKNAME_CATEGORYNAME_CARDNAME”, for example “Databox_Data_Bank”. Please use only letters, numbers, ‘’ and ‘-’ in an ID (any spaces will be converted to ‘’ in filenames). But note that card backs have IDs like "back:BACKNAME".
- “name”, the human-readable name of the card, which will be shown analysis views (if defined)
- “description”, a description of the card, which will also be available in analysis views.
- “category”, an assignment of the card to a particular group (cf a suit in normal playing cards), which will also be available in analysis views
- “back”, the name of the “back” for this card (i.e. its ID, but without "back:"). Again, please use only letters, numbers, ‘’ and ‘-’ in an ID (any spaces will be converted to ‘’ in filenames).
- “attribute”, a user-defined column with no special meaning (but still usable when building cards).
- "frontUrl", the URL of the card face image used e.g. by the cardographer web app (set internally if the deck is built in cardographer, but can be used to make a deck using existing images)
- (TODO: “aka” support for legacy IDs)
Note, if you are making a deck where each category has a different back then you will need 2 columns with (almost) the same values, one of type “category” (used in the analysis) and one of type “back” (used to specify the matching back).
In general you should be able to download the CSV definitions from one deck and upload it to a new deck to create the same cards.
Or download it, edit it (adding, removing and changing cards) and upload it again, for example if you lose the original CSV file.
However, note that currently:
- You can add more columns – just add them to the spreadsheet and upload it
- You can change a column’s use – just change that use: value and upload it
- You CANNOT change a column’s name or delete a column that exists (you'll have to start a new Deck if you run into trouble like this)
- A “card:” row with an ID that starts with “back:” defines a card back, not a card (e.g. “back:Data” defines the back “Data”)
- A back row should be given the type “back:” but currently these rows are discarded, so use row type “card:” for now.
If you upload a CSV file that doesn’t start with “title:” then the platform will assume that the first row is still the column name. For new columns with no “use:” row the default use is based on the name, e.g. a new column called “description” would be assumed to be (i.e. have use) a description. You may find it easier to maintain or generate a card definition CSV file in this simpler form. However, in this case you will still need to create or edit the extended CSV definition at least once in order to set/check the column use and export settings: at present "export:" defaults to no, which typically means that the card building process won't work until/unless you download the CSV, set "export:" to "Y" for most/all columns, and upload it again.
The process of generating card images from the card definitions is called “building” and it done under the deck (and revision) “Build” tab.
The view shows the build-related files that currently exist (if any) and (top left) (2 or) 3 iconic options:
- Build (hammer), which attempt to run the card build process
- Download, which will download a zip file of all the visible files (this isn't shown if there are no files)
- Upload, which will open a dialog allowing you to upload/replace files for use in this revision of the current deck.
In you upload a ZIP file it will be unpacked automatically, e.g. if you want to upload several images at once. But note that the upload size is typically limited to a few MB, so you may need to scale images.
The trash can icon will delete the corresponding file (or directory).
If you created a deck from “Create Empty Deck” then there will be no files, and you will need to upload everything you need.
If you have already created your cards elsewhere (e.g. using InDesign or Illustrator) then the simplest way to make them available within Cardographer is to create a simple card definition which uses your existing full-card images.
A deck created in this way should work in the Cardographer web app but not in the virtual tabletop; if you need to generate additional output files (atlas files or PDFs) then you will need to rebuild the cards from the face images as described below under "Re-building Existing Cards".
As minimum this will need to specify the card ID ("ID") and card face image URL ("frontUrl"). But it is useful to include the card title, description, category, etc. (e.g. for subsequent analysis or in future accessibility).
Then:
- Upload the initial card definition CSV file
- Go to the build tab and Upload the card face images (e.g. as a ZIP file) (this assumes that you want to host the card image files on Cardographer)
- Make a note of the URL of the uploaded image files (which will be something like "https://cardographer.cs.nott.ac.uk/uploads/.../1/images/...png")
- Populate the CSV file column "frontUrl" with the respective card face image URL
- Re-upload the card definition CSV file
That's all. In fact, you might want to "Disable re-build" in the Deck settings so that you don't accidentally break anything you have uploaded.
If you now want to share the deck electronically (i.e. in the Cardographer webapp) then create a new session and add this deck to it, then share the session's "cards" URL.
Given enough information, Cardographer can "build", i.e. generate, the card images and other related files (e.g. atlas files for unity and PDF files for printing).
The build process should either create a new set of card images in the “_output” directory, or show an error message from the card builder above the file list. These errors tend to be very technical and hard to interpret!
Squib is a fairly complicated tool written in Ruby for creating card images from spreadsheets (CSV files).
Also note that the initial deck builder uses “squib”, which will only handle PNG and SVG images/icons (not JPEGs). See squib and docs
If you use the Databox template (or similar) you will see the following important initial files:
- “deck.rb” – the Ruby program that is run by the deck builder.
- “options.yml” – default build options that are used by deck.rb, e.g. to specify card size and DPI. Some options here are over-ridden by the build process (e.g. some of the file name options).
- “config.yml” – some default squib configuration, e.g. for warnings. You probably won’t need to change this.
- “layout.yml” – defines that layout of visual elements on the cards, and is a key part of using squib. The default units are pixels but other units including “mm” and “cells” or “c” (0.125 inches) can be used for resolution-independent positioning.
You should find some examples in github.
Note that setting even_is_back: true in "options.yml" will cause Cardographer to (additionally) run deck.rb on the entire deck of cards, alternating fronts and backs in the CSV file. This can be used to generate a print-ready PDF file (see Printing Cards).
deck.rb is where all the work is done. It:
- Reads the options file
- Reads the CSV file defining the cards to generate
- Calls “Squib::Deck.new” which will make the deck, and within that is
- A sequence of lines which add a visual element to all (or a subset of) the cards being generated
- A final set of “save_...” commands which generate the output files.
Examples of squib visual commands/elements include:
- “background” – whole card background colour
- “text” – some text
- “png” or “svg” – insert a PNG or SVG file
Notes:
- if you want to change the size (or print bleed) of the cards then do this as early as possible before tweaking any other aspects of the layout (see also Printing Cards).
- squib doesn't support JPG files, so you'll need to convert them externally or from deck.rb (but see for example jpg2png.rb)
- arguments like “layout: ‘description’” tell squib to position that visual element according to the corresponding definition in the layout file (layout.yml).
- expressions like “data[‘name’]” mean the values in the “name” column of the spreadsheet.
After a build has completed you will also see (per back) “.csv” files, which contain the card definition data used by the build and per-back “_options.yml” files, which include the specific options used. But note that individual card image files are renamed at the end of the build to match the card ID in the spreadsheet.
For more details of how to use squib to create particular card layouts please refer to squib’s own documentation, https://squib.rocks/ & https://squib.readthedocs.io/
To download your card images, for example for use in Miro, after a successful build click on the “_output” folder and either download all the output as a zip (Download/down arrow icon) or open and save each individual image.
The default squib builder will build three outputs:
- Individual PNG file images, with filename the same as the card ID
- Card “atlas” images (PNG files named after the card back, “Atlas” and a page number), to be used in the virtual tabletop interface, where one image includes the fronts of the several cards. There is a different atlas for each card back in the deck.
- Printable card PDF files (named after the card back and “_output”), which have cut markings for easily cutting out a copy of each card. (although currently there will not be enough back back images to go around…).
If you have already created your cards elsewhere (e.g. using InDesign or Illustrator) then the simplest way to make them available within Cardographer is to currently to use a simple Squib card generator which uses your existing full-card images on otherwise blank cards. See the MRT cards builder as an example. You will need to upload the card face/back images to Cardographer (probably in a new build sub-directory).
You will also need to have and upload a card metadata CSV file. As minimum this will need to specify the card ID, existing image name (if different) and card back. But it is useful to include the card title, description, etc. (e.g. for subsequent analysis or in future accessibility).
Note again that squib doesn't support JPG files, so if your existing card face images are JPGs then you'll need to convert them externally to PNGs, or do it programmatically from deck.rb (see for example jpg2png.rb)