sarina-cli

Sarina

---

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

• Introduction
• Installation
• Usage
• How It Works

---

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 or pip3 install sarina-cli

Source code

• Clone the repository or download the source code.
• Run pip3 install -r requirements.txt or pip 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.