Sarina: An ASCII Art generator command line tool to create word clouds from text words based on contours of the given image.
The program is dedicated to Sarina Esmailzadeh, a 16-year-old teenager who lost her life during the Mahsa Amini protests, as a result of violence inflicted by the IRGC forces. Her memory serves as a reminder of the importance of justice and human rights. |
Table of contents
Overview
Sarina is an ASCII art generator written in Python3 and C++. It transforms an input image and a text file containing words and their weights into a unique ASCII art representation. The algorithm behind Sarina is randomized, ensuring that every output is distinct, even for identical inputs.
Installation
PyPI
- Check Python Packaging User Guide
- Run
pip install sarina-cli
orpip3 install sarina-cli
Source code
- Clone the repository or download the source code.
- Run
pip3 install -r requirements.txt
orpip install -r requirements.txt
Usage
Default image and words
Amin@Maximus:Sarina $ sarina
Sarina is generating your word cloud...
100%|βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ| 132/132 [01:09<00:00, 1.89it/s]
Done!
Images are saved in ./results
Input Image | Generated Output | Generated Output | Generated Output | Generated Output | Generated Output |
Custom image and options
Amin@Maximus:Sarina $ sarina -if 'assets/images/Sarina.png' -ct 100 -ft 20 -tc [255,255,255] -pc -cs
Enter the contour indices to keep (+) or to remove (-) (separated by space): +1 -2 -3 -4
Sarina is generating your word cloud...
100%|βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ| 132/132 [01:06<00:00, 1.98it/s]
Done!
Images are saved in ./results
Input Image | Generated Output | Generated Output | Generated Output | Generated Output | Generated Output |
To learn more about the options, you can use the following command:
Amin@Maximus:Sarina $ sarina --help
Usage: sarina [OPTIONS]
Sarina: An ASCII Art Generator to create word clouds from text files based
on image contours
Options:
-if, --img_file PATH Path to image file
-tf, --txt_file PATH Path to text file. Each line of the text
file should be in the following format:
WORD|WEIGHT
-cs, --contour_selection Contour selection - if selected, user will
be prompted to enter the contours index. For
example, if you want to keep the contours
with index 0, 3, 4, and remove contours with
index 1, 2, you should enter +0 +3 +4 -1 -2
-ct, --contour_treshold INTEGER RANGE
Threshold value to detect the contours.
Sarina uses intensity thresholding to detect
the contours. The higher the value, the more
contours will be detected but the less
accurate the result will be [default: 100;
0<=x<=255]
--max_iter INTEGER RANGE Maximum number of iterations. Higher number
of iterations will result in more consistent
results with the given texts and weights,
but it will take more time to generate the
result [default: 1000; 100<=x<=10000]
--decay_rate FLOAT RANGE Decay rate for font scale. Higher decay rate
will result in more consistent results with
the given texts and weights, but it will
take more time to generate the result
[default: 0.9; 0.1<=x<=1.0]
-ft, --font_thickness INTEGER Font thickness. Higher values will make the
texts font thicker. Choose this value based
on the size of the image [default: 10]
--margin INTEGER RANGE Margin between texts in pixels. Higher
values will result in more space between the
texts [default: 20; 0<=x<=100]
-tc, --text_color TEXT Text color in RGB format. For example,
[255,0,0] is red. Note to use square
brackets and commas. Also, just enter the
numbers, do not use spaces [default:
[0,0,0]]
-pc, --plot_contour Plot contour on the generated images. If
selected, the generated images will be
plotted with the detected/selected contours
-op, --opacity If selected, opacity of each text will be
selected based on its weight [default:
True]
-sp, --save_path PATH Path to save the generated images. If not
selected, the generated images will be saved
in the same results folder in the directory
as the function is called.