A bash script to query our API for public domain artworks and render them as ASCII art
Just a small side-project we did to show what could be done with our museum's API.
The Art Institute of Chicago (AIC) offers all of its public data via a centralized, searchable API. There, you can find data on artworks, artists, and places represented in our collection, and much more besides. For more information, check out our Open Access initiatives.
Please read this section in its entirety before installing anything.
- A terminal with truecolor (24bit) support (recommendations below)
- Bash v4.2 (Feb. 2011) or higher
- coreutils (for realpath)
- jp2a v1.0.6
- ImageMagick (only for
Not all terminals support truecolor! See TrueColor.md for more information.
New to the command-line life? From testing, we recommend the following:
- macOS: iTerm2 v3
- Win 10: Cmder + WSL (see Maximus5/ConEmu#920)
Note that the default Terminal.app which ships with macOS does not support truecolor.
Likewise, macOS's default bash is locked to
3.2.57(1)-release due to licensing issues. Instructions for upgrading:
Lastly, jq and jp2a must be reachable via
$PATH. You can install them using a package manager of your choice.
# macOS with Homebrew brew install jq coreutils brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/31b5579ccb72ccf24e9d01962e422aece563cff5/Formula/jp2a.rb # Ubuntu with APT sudo apt-get install jq jp2a coreutils
Debugging jp2a issues
On macOS, if you see errors such as the following:
$ ./aic.sh --id 27992 ./aic.sh: line 428: 16#'cl,''l:'..........; : syntax error: invalid arithmetic operator (error token is "'cl,''l:'..........; ") $ ./aic.sh --id 28560 ./aic.sh: line 428: 16#,.''ooolxOc.;cooollllcllollllcclllllllloxxdxxdocclollc:cdxxxdlcokxdoolccldddxdddddddll;clcc,c : syntax error: operand expected (error token is ".''ooolxOc.;cooollllcllollllcclllllllloxxdxxdocclollc:cdxxxdlcokxdoolccldddxdddddddll;clcc,c ")
...you probably have jp2a v1.0.7, which is broken. Check here for more context:
You can confirm this by running
$ brew info jp2a jp2a: stable 1.0.7 (bottled) Convert JPG images to ASCII https://csl.name/jp2a/ /usr/local/Cellar/jp2a/1.0.7 (9 files, 67.7KB) * <-- this should be 1.0.6_1 Poured from bottle on 2019-09-06 at 15:59:33 From: https://github.com/Homebrew/homebrew-core/blob/master/Formula/jp2a.rb
You can fix this by running the following commands:
brew unlink jp2a brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/31b5579ccb72ccf24e9d01962e422aece563cff5/Formula/jp2a.rb
On Ubuntu, you should be fine. Double-check that
1.0.6-6build1 is installed.
For now, just clone this repository to wherever you store code on your system:
git clone https://github.com/art-institute-of-chicago/aic-bash
If you'd like to run
aic.sh from anywhere, you can add the repository directory to your
# Add this to your ~/.bashrc or equivalent, then open a new terminal instance export PATH=/path/to/aic-bash:$PATH
You can also run
aic.sh when you start a new terminal session:
# Add this to your ~/.bashrc or equivalent, then open a new terminal instance /path/to/aic-bash/aic.sh --quality medium --ratio 120
quality to reduce color artifacts or improve performance.
--ratio 120 is aimed at iTerm users. Although terminal fonts tend to be monospace, not all of them will have the same aspect ratio for each character. We can use
ratio to stretch or compress the width to compensate for these differences. In this example,
--ratio 120 will stretch the width to 120% of original, which is ideal for iTerm users who use default settings.
$ ./aic.sh -h usage: aic.sh [options] [query] -c, --cache [num] Cache results of this query for [num] seconds. [num] defaults to 1 hour (3600 sec) if blank. Use cached results if available. -i, --id <id> Retrieve specific artwork via numeric id. -j, --json <path> Path to JSON file containing a query to run. -l, --limit <num> How many artworks to retrieve. Defaults to 1. One random artwork from results will be shown. -n, --no-fill Disable background color fill. -q, --quality <enum> Affects width of image retrieved from server. Reduces color artifacts. Valid options: h, high = 843x (default) m, medium = 400x l, low = 200x -r, --ratio <num> Stretch the width by this percent of original. Useful to compensate for terminal font aspect. (iTerm users, try `120` for less stretching.) -s, --seed <val> For random queries. Defaults to timestamp. [query] (Optional) Full-text search string.
aic.sh has four modes of operation:
Running it without any arguments will return a random public domain oil painting.
Running it with the
--idoption will look up a specific artwork by its identifier:
# Stacks of Wheat (End of Summer) by Claude Monet ./aic.sh --id 64818
Running it with a string argument will perform a full-text search and show the first result:
# The Bedroom by Vincent Van Gogh ./aic.sh bedroom # Be sure to use quotes when searching for phrases! ./aic.sh "la grande jatte" # With --limit, show a random artwork from the top <num> results ./aic.sh --limit 10 "mountains"
Running it with
--jsonwill query our API using a query stored in the specified JSON file:
# Just some example queries we included for reference ./aic.sh --json "queries/default-random-asian-art.json" ./aic.sh --json "queries/default-random-landscape.json"
Please note that these queries will only return public domain artworks.
Under the hood, all of its queries are stored as JSON files in the
We treat JSON files as query templates. Before executing a JSON query, we replace the following text:
VAR_FULLTEXTis replaced by whatever is specified in the
VAR_SEEDis replaced by the value of the
--seedoption or the current Unix timestamp
VAR_LIMITis replaced by the value of the
VAR_IDis replaced by the value of the
So if the query supports it, you can combine
--json with full-text search:
# Flower Girl in Holland by George Hitchcock ./aic.sh --json "queries/default-fulltext-landscape.json" "holland"
If you want to write custom queries for use with
--json, feel free to store them in the
Any file in
./queries that doesn't begin with
default-* will be ignored by version control.
--limit <num> option provides a way to randomize search, assuming that the query in question uses
Here, "limit" indicates how many results should be returned on each page from the API. Internally, we show a random result from the first page. By default, limit is set to
1, so the top result will always be shown. Specifying a greater limit means that we will select a random artwork from the top
<num> results from the API. For performance, limit is capped at 100.
Limit is meant to work primarily in conjunction with full-text search. For example:
# Show a random artwork from the top 50 results for "paperweight" ./aic.sh --limit 50 "paperweight"
If you are writing your own queries, and you'd like to select a random artwork from a category, with no regard to relevance or popularity, consider avoiding the use of
VAR_LIMIT. Instead, use term queries with function_score and
"boost": false. See queries/default-random-landscape.json for an example.
--cache [num] allows you to cache the API response, so that the script won't have to hit the API each time it runs the same query. This is useful for running full-text search with high limit. For example:
# Show a random artwork from the top 100 results for "paperweight" # Results will be cached for 1 day (86400 seconds) ./aic.sh --limit 100 --cache 86400 "paperweight"
After running this query once, it will cache the results. If you run it again within the 24-hour window, it'll show a new random paperweight from the top 100 results without needing to re-query the API.
If you use
--cache without specifying
[num], it'll default to 3600 seconds, i.e. 1 hour.
We encourage your contributions. Please fork this repository and make your changes in a separate branch. To better understand how we organize our code, please review our version control guidelines.
# Clone the repo to your computer git clone email@example.com:your-github-account/aic-bash.git # Enter the folder that was created by the clone cd aic-bash # Start a feature branch git checkout -b feature/good-short-description # ... make some changes, commit your code # Push your branch to GitHub git push origin feature/good-short-description
Then on GitHub, create a Pull Request to merge your changes into our
This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
We welcome bug reports and questions under GitHub's Issues. For other concerns, you can reach our engineering team at firstname.lastname@example.org
This project is licensed under the GNU Affero General Public License Version 3.