` elemen each.
41 | The entire text output is wrapped in a `
` element.
42 |
43 | ??? abstract "Source"
44 | Refer to the [`unify` function][picharsso.format.html.HtmlFormatter.unify]
45 | for more information.
46 |
--------------------------------------------------------------------------------
/docs/formats/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Formats - Picharsso"
3 | description: "An overview of the output formats of Picharsso"
4 | ---
5 |
6 | # Formats
7 |
8 | After an `image` is coverted to a `text_matrix`,
9 | it must be formatted before it can be output.
10 |
11 | ## Procedure
12 |
13 | There are steps involved in this process that are common to
14 | all `formatters`.
15 | Picharsso defines a [`BaseFormatter`][picharsso.format.base.BaseFormatter]
16 | that abstracts this general procedure.
17 |
18 | ### Initialization
19 |
20 | This step assigns values to the parameters for the algorithms.
21 |
22 | #### Color
23 |
24 | The `colorize` parameter controls whether the output text must include the colors from the image.
25 |
26 | Consider the following image:
27 |
28 |
29 |
30 | 
31 |
32 |
33 | Instagram
34 |
35 |
36 |
37 | Here's what it should look like:
38 |
39 | === "colorize = False"
40 |
41 |
45 |
46 |
47 | === "True"
48 |
49 |
53 |
54 |
55 | #### Vectorization
56 |
57 | The `vcolor` attribute is a vectorized version of the `color` method.
58 |
59 | ### Translation
60 |
61 | The elements of the `text_matrix` are encoded in the Unicode standard.
62 |
63 | Depending on the output format, these characters must be translated accordingly.
64 |
65 | ??? abstract "Source"
66 | Refer to the [`translate` function][picharsso.format.base.BaseFormatter.translate] for more information.
67 |
68 | ### Colorization
69 |
70 | Colors are pooled from the original `image` by resizing it to the dimensions of the output text.
71 | This ensures that each character has a unique pixel, and thus, a unique color.
72 |
73 | With the vectorized `color` method, `vcolor`, the elements of the `text_matrix`
74 | are transformed into strings of text that represent
75 | the original character as well as its color.
76 |
77 |
78 |
79 |
80 |
81 | ??? abstract "Source"
82 | Refer to the [`color` function][picharsso.format.base.BaseFormatter.color] for more information.
83 |
84 | ### Unification
85 |
86 | Finally, the `text_matrix` is unified into a single string of text.
87 | This text, when viewed through a means supporting the particular format,
88 | should look like the original image.
89 |
90 | ??? abstract "Source"
91 | Refer to the [`unify` function][picharsso.format.base.BaseFormatter.unify] for more information.
92 |
93 | ## Varities
94 |
95 | All the following formats are implemented by a `formatter`
96 | which inherits from the [`BaseFormatter`][picharsso.format.base.BaseFormatter].
97 |
98 | ### ANSI
99 | : The [ANSI format](ansi.md) is implemented by the [`AnsiFormater`][picharsso.format.ansi.AnsiFormatter].
100 |
101 | ### HTML
102 | : The [HTML format](html.md) is implemented by the [`HtmlFormater`][picharsso.format.html.HtmlFormatter].
103 |
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | # Picharsso
2 |
3 |
4 |
5 | 
6 |
7 |
8 | A utility for converting images to text art.
9 |
10 |
11 |
12 | ## Installation
13 |
14 | Run the following command:
15 |
16 | ```bash
17 | pip install picharsso
18 | ```
19 |
20 | This will:
21 |
22 | * download and install the [`picharsso` Python package](https://pypi.org/project/picharsso/){target=_blank}
23 | (along with its dependencies).
24 | * create an executable, `picharsso`, for the CLI (command line interface).
25 |
26 | ??? success "Verification"
27 | To verify that Picharsso is installed, run:
28 |
29 | ```bash
30 | python -c "import picharsso"
31 | ```
32 |
33 | ## Commands (CLI)
34 |
35 | Picharsso ships with a CLI that provides some basic functionality from the terminal.
36 |
37 | ??? question "Usage"
38 | Run the following command to display a helpful message:
39 |
40 | ```bash
41 | picharsso -h
42 | ```
43 |
44 | ```
45 | --8<-- "docs/snippets/cli/help.txt"
46 | ```
47 |
48 | Consider the following image:
49 |
50 |
51 |
52 | 
53 |
54 |
55 | Apple Computer [Rob Janoff, 1977]
56 |
57 |
58 |
59 | To convert an image to text art, run:
60 |
61 | === "Braille"
62 | ```bash
63 | picharsso draw -c -H 32
braille
64 | ```
65 |
66 | Here's what it should look like:
67 |
68 |
69 |
73 |
90 |
94 |
157 |
158 | 
159 |
160 |
161 | Nyan Cat
162 |
163 |
215 |
219 |
269 |
273 |
14 |
15 | 
16 |
17 |
18 | Apple Computer [Rob Janoff, 1977]
19 |
20 |
25 |
29 |
58 |
59 | 
60 |
61 |
62 | Tiles ressembling GitHub contributions
63 |
64 |
70 |
74 |
78 |
82 |
86 |
90 |
94 |
98 |
102 |
106 |
162 |
163 |
14 |
15 |
16 |
17 |
18 | Apple Computer [Rob Janoff, 1977]
19 |
20 |
25 |
29 |
49 |
50 | 
51 |
52 |
53 | Slack
54 |
55 |
61 |
65 |
69 |
73 |
77 |
81 |
85 |
89 |
98 |
99 | 
100 |
101 |
102 | GitHub
103 |
104 |
110 |
114 |
118 |
122 |
156 |
157 |
31 |
32 | 
33 |
34 |
35 | Zima Blue [Zima]
36 |
37 |
43 |
47 |
51 |
55 |
59 |
63 |
67 |
71 |
95 |
96 | 
97 |
98 |
99 | Starry Night [Vincent van Gogh, 1889]
100 |
101 |
107 |
111 |
115 |
119 |
123 |
127 |
131 |
135 |
139 |
143 |
147 |
151 |
178 |
179 |
190 |
191 |
221 |
222 | 
223 |
224 |
225 | Apple Computer [Rob Janoff, 1977]
226 |
227 |
236 |
240 |
247 |
251 |
8 |
9 |
10 |
11 |
12 | Apple Computer [Rob Janoff, 1977]
13 |
14 |
19 |
23 |
8 |
9 |
10 |
11 |
12 | Apple Computer [Rob Janoff, 1977]
13 |
14 |
19 |
23 |
".format(
45 | "\n".join([f"
{''.join(row)}
" for row in text_matrix])
46 | )
47 |
48 |
49 | __all__ = ["HtmlFormatter", "HTML_ENTITY_MAP"]
50 |
--------------------------------------------------------------------------------
/src/meta.py:
--------------------------------------------------------------------------------
1 | """This module defines variables for the package metadata."""
2 |
3 | NAME: str = "picharsso"
4 | """The package name."""
5 |
6 | DESCRIPTION: str = "A utility for converting images to text art."
7 | """The package description."""
8 |
9 | VERSION: str = "2.0.1"
10 | """The current package version.
11 | """
12 |
13 | REPO_URL: str = f"https://github.com/kelvindecosta/{NAME}"
14 | """The URL of the package source code."""
15 |
16 | DOCS_URL: str = f"https://kelvindecosta.github.io/{NAME}"
17 | """The URL of the package documentation."""
18 |
19 | AUTHOR: str = "Kelvin DeCosta"
20 | """The package author."""
21 |
22 | LICENSE: str = "MIT"
23 | """The package license."""
24 |
--------------------------------------------------------------------------------
/src/utils.py:
--------------------------------------------------------------------------------
1 | """This module defines utility functions that are used across the package."""
2 |
3 | from os import system, name
4 | import shutil
5 |
6 | import numpy as np
7 | from PIL import Image
8 | from sty import ef, rs
9 |
10 |
11 | def clear_screen():
12 | """Clears the terminal console."""
13 | # Windows systems
14 | if name == "nt":
15 | _ = system("cls")
16 | # Unix systems
17 | else:
18 | _ = system("clear")
19 |
20 |
21 | def embolden(text):
22 | """Modifies text to appear in a bold typeface,
23 | using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
24 |
25 | Args:
26 | text (str): The subject text.
27 |
28 | Returns:
29 | str: The text in a bold typeface.
30 | """
31 | return f"{ef.bold}{text}{rs.bold_dim}"
32 |
33 |
34 | def ensure_rgb(image):
35 | """Usually converts any [Pillow](https://python-pillow.org/)
36 | `image` to its equivalent in the `RGB` mode.
37 |
38 | Args:
39 | image (PIL.Image.Image): The subject image.
40 |
41 | Returns:
42 | PIL.Image.Image: The image in the `RGB` mode.
43 | """
44 | # If the image has a color palette,
45 | # convert to the `RGBA` mode.
46 | if image.mode == "P":
47 | image = image.convert("RGBA")
48 |
49 | # If the image is in `RGBA` mode,
50 | # create a white background.
51 | if image.mode == "RGBA":
52 | temp = Image.new("RGB", image.size, (255, 255, 255))
53 | temp.paste(image, mask=image.split()[3])
54 | image = temp
55 |
56 | # Convert to `RGB` mode
57 | return image.convert("RGB")
58 |
59 |
60 | def italicize(text):
61 | """Modifies text to appear in italics,
62 | using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
63 |
64 | Args:
65 | text (str): The subject text.
66 |
67 | Returns:
68 | str: The text in italics.
69 | """
70 | return f"{ef.italic}{text}{rs.italic}"
71 |
72 |
73 | def submatrices(matrix, shape):
74 | """Returns a rolling window view of a `matrix`, without overlapping,
75 | given the `shape` of the window.
76 |
77 | Args:
78 | matrix (numpy.ndarray): The subject matrix.
79 | shape (Tuple[int, int]): The `
` and `` of the window.
80 |
81 | Returns:
82 | numpy.ndarray: The rolling window view of the matrix.
83 |
84 | Note:
85 | This operation doesn't account for the loss of border elements.
86 | """
87 | # Extract strides and shapes for calculation.
88 | mat_hs, mat_ws = matrix.strides[:2]
89 | mat_h, mat_w = matrix.shape[:2]
90 | ker_h, ker_w = shape
91 |
92 | # View `matrix` according to new strides and shape.
93 | return np.lib.stride_tricks.as_strided(
94 | matrix,
95 | (1 + (mat_h - ker_h) // ker_h, 1 + (mat_w - ker_w) // ker_w, ker_h, ker_w)
96 | + matrix.shape[2:],
97 | strides=(ker_h * mat_hs, ker_w * mat_ws, mat_hs, mat_ws) + matrix.strides[2:],
98 | )
99 |
100 |
101 | def terminal_size():
102 | """Returns the size of the terminal window.
103 |
104 | Returns:
105 | (Tuple[int, int]): The `` and ``
106 | of the terminal window in characters.
107 |
108 | Note:
109 | When used while piping,
110 | this function usually returns the default terminal size, `(24, 80)`.
111 | """
112 | return shutil.get_terminal_size()[::-1]
113 |
114 |
115 | __all__ = [
116 | "clear_screen",
117 | "embolden",
118 | "ensure_rgb",
119 | "italicize",
120 | "submatrices",
121 | "terminal_size",
122 | ]
123 |
--------------------------------------------------------------------------------
6 |
7 | 
11 | 
12 | 
13 | 
77 | 
94 | 
134 | 
145 | 
202 | 
16 | 
29 | 
48 | 
66 | 
74 | 
82 | 
90 | 
98 | 
29 | 
48 | 
66 | 
74 | 
82 | 
90 | 
101 | 
119 | 
127 | 
32 | 
50 | 
58 | 
76 | 
94 | 
102 | 
110 | 
118 | 
126 | 
134 | 
149 | 
166 | 
198 | 
226 | 
259 | 
21 | 
34 | 
22 | 
36 |