Debian Codegraph @

README

raw
1 jp2a
2 ====
3
4 ![full-check](https://github.com/Talinx/jp2a/workflows/full-check/badge.svg?branch=master)
5
6
7 jp2a is a simple JPEG/PNG/WebP to ASCII converter.
8
9 The source is available at <https://github.com/Talinx/jp2a>. This project
10 used to be hosted on SourceForge.
11
12 License
13 -------
14
15 Copyright 2006-2016 Christian Stigen Larsen and 2020-2024 Christoph Raitzig
16 Distributed under the GNU General Public License v2.
17
18 You can read the full license in the file COPYING. jp2a also uses other
19 libraries. These licenses can be found in the file LICENSES.
20
21 Example: Oswald the lucky rabbit
22 --------------------------------
23 ......
24 .:lOKMMMMMMMMMM0l
25 .;dOMMMMMMMMMMMMMMMMMMW.
26 .ckWMMMMMMMMMMMMMMMMMMMMMMMO
27 .dXMMMMMMMMMMMMMMMMMMMMMMMMMMO
28 .xWMMMMMMMMMMMMMMMMMMMMMMMMMMO:.
29 lXMMMMMMMMMMMMMMMMMMMMMWOOxc'
30 .;lxOOOOOxdl:. cMMMMMMMMMMMMMMMMWKklc'..
31 'llc.. ..:oMMMMMMKxNMMMMMMMMMM0kl:'.
32 :0' cMMMMMMMMMMMMWd'.
33 .K:l0 .MMMMMMMMMMl.
34 ,K W ,MMMMMMMMMMMMN0dl'
35 M. M MMMMMMMMMMMMMMMMMMKx:.
36 cMMK WMMMMMMMMMMMMMMMMMMMMMXd'
37 NMMM: MMMMMMMMMMMXWMMMMMMMMMMMMNd'
38 KMMMW MMMMMMMMMMM' ;XMMMMMMMMMMMMMWd'
39 MMMM XMMMMMMMMMMM dMMMMMMMMMMMMMMMNc
40 '' NMKWl' .KMMMMMMMMMMM' :MMMMMMMMMMMMMMMMMd
41 KMWMKOk ' ,lXMMMMMMMMMMM; .KMMMMMMMMMMMMMMMM0
42 KMMMMM. .cOMMMMMW' kMMMMMMMMMMMMMMMMX
43 cOXMNXl. ...... .MWd. .0cc:' .NMMMMMMMMMMMMMMMk
44 .cololoxKWWWXWMMMMMMM: M c:. .l0ok oMMMMMMMMMMMMMMM
45 .'Mo,MMMMNk:lO' :l .OMMMMl .OMMMMMMMMMMMMN
46 X0'OkxkxOK;. :: ,.XMMMMMMO :O lXMMMMMMMMk
47 kc,,o0M0.:;c'N ko;lMMMMMM:'xMMMNWKO,.clxdl:.
48 ;00xkM:d , .. oMMMMMM cMMMMMMMMl
49 c N0l . .l:;;oKMMk MMMMMMMMM0
50 O ,.ocOc..l..k' .:c;'O 0MMMMMMMX.
51 X N..l .c K. OMMMMMMM
52 .' c. : M . OMMM0,.;
53 :, N.;W ; O...o .,.
54 d M ;X' :l :
55 d..':. lcKol,,,,'.:c,,'.cd;'o,'.
56 . ;:,WMMMMMMXx,; M0XXNNWM.
57 MMMMMMMM .MMMMMMMM
58 MMMMMMMM .MMMMMMMM.
59 :ONMMMMMM0:':MMMMMMMMM:
60 ;c:,'',::lX' '','' .MMMMMMMMMMWK:c:
61 x. .lloc;.',lxl..lKMMMMMKl M
62 0 .;,;'......;::c' .. ;dl;l'
63 ;O: .d' .lkk::::;, 'k
64 N.'oc'. M : X
65 lo:. ',::xN: .x0'
66 .,lccccM .ll,. . ;;:::;c'.0
67 .kl. .c::lcccccc:cc::; .''clccl.
68 'lcl:lc::,,'::cc:cc:c,..
69
70 The Oswald character is Copyright Walt Disney, and, unfortunately, not in the
71 public domain. However, I believe that I can use this picture under the fair
72 use clause, for demonstrational purposes, especially in low-resolution, ASCII
73 format. If I am wrong, I will promptly remove it.
74
75 Installation
76 ------------
77
78 Look in your system's package manager. I don't maintain Windows binaries
79 anymore.
80
81 Graphical UI
82 ------------
83
84 [Letterpress](https://apps.gnome.org/Letterpress/) is a graphical user interface
85 for jp2a. Letterpress can be installed from
86 [Flathub](https://flathub.org/apps/io.gitlab.gregorni.Letterpress).
87
88 Docker
89 ------
90
91 You can run jp2a using [Docker](https://www.docker.com/):
92 ```
93 docker run -t --rm -e COLORTERM="$COLORTERM" -v "$(pwd)":/app talinx/jp2a [options] <filenames or URLs>
94 ```
95 See [hub.docker.com/r/talinx/jp2a](https://hub.docker.com/r/talinx/jp2a) for details.
96
97 Building
98 --------
99
100 `jp2a` can be compiled as usual: `./configure && make && make install`
101
102 If you want to compile after cloning the git repo (i.e. generate the `configure` script yourself), you need autotools, automake and optionally autoconf-archive. You may need to specify the path to jpeglib. I usually just do
103
104 autoreconf -vi
105 ./configure --with-jpeg-prefix=/usr/local \
106 --with-curl-config=`which curl-config`
107 make -j
108
109 Before installing, you may want to check that jp2a works by running `src/jp2a`
110 on some `.jpg` and `.png` files. You can also use `make check`. When you're ready to install,
111
112 make -j install
113
114 Extract the archive and follow the instructions inside 'install.txt' to build and
115 install it. For a default install, the corresponding `.so` (shared object) files
116 will be present in `/usr/local/lib/`
117
118 Next, run the command `ldconfig` (escalated privileges may be required) to configure dynamic linker run-time bindings. See
119 its man page for more details. The configure command should work after that.
120
121 If configure can't automatically find jpeglib, specify with
122
123 ./configure --with-jpeg-include=PATH --with-jpeg-lib=PATH
124
125 or you can just type the prefix
126
127 ./configure --with-jpeg-prefix=/usr/local/
128
129 You can also compile jp2a with libcurl, so it can automatically download images
130 from the net:
131
132 ./configure --enable-curl
133
134 This will look for `curl-config` in $PATH, but you can specify it directly with
135 `--with-curl-config=PATH` if you need to.
136
137 ### Documentation
138
139 jp2a is documented with [doxygen](https://www.doxygen.nl/). To build the documentation you need doxygen installed. It can then be built with:
140
141 autoreconf -vi
142 ./configure
143 make doc
144
145 This will create HTML and LaTeX documentation in the doxygen-doc folder.
146
147 ### Runtime dependencies
148 - [jpeglib](https://www.ijg.org/) or [libjpeg-turbo](https://libjpeg-turbo.org/)
149 - [libpng](http://libpng.org/pub/png/libpng.html)
150 - [libwebp](https://developers.google.com/speed/webp/)
151 - [curl](https://curl.haxx.se/) (optional)
152 - [ncurses](https://invisible-island.net/ncurses/ncurses.html) (optional)
153 - [libexif](https://libexif.github.io/)
154
155 ### Build dependencies
156 - make (e.g. [GNU Make](https://www.gnu.org/software/make/))
157 - a C compiler like [gcc](https://gcc.gnu.org/)
158
159 If you generate the `configure` script yourself (i.e. run `autoreconf`) you also need these:
160
161 - autotools
162 - [automake](https://www.gnu.org/software/automake/)
163 - [autoconf](https://www.gnu.org/software/autoconf/autoconf.html)
164 - (optional, only required for building documentation) [autoconf-archive](https://www.gnu.org/software/autoconf-archive/)
165
166 Windows
167 -------
168
169 ### Cross compiling
170
171 You can cross compile.
172
173 ### WSL
174
175 You can use the Windows Subsystem for Linux.
176
177 ### Compile with `configure`
178
179 The `configure` script requires a Bourne shell, so you got to install one (e.g. Bash).
180 The easiest way is to install [Cygwin](https://cygwin.com/). Make sure to install the used libraries (curl, jpeglib, libpng, ncurses) as well as gcc and make.
181 Open Cygwin and proceed as usual: `./configure && make && make install`
182
183 You can also "cross compile" with Cygwin so that you get a binary that does not depend on Cygwin.
184
185 ### Compile without `configure`
186
187 You need a working jpeglib for Windows and set up include paths yourself.
188 You will need to manually type out a `config.h` file. Example:
189
190 WIN32
191 NDEBUG
192 _CONSOLE
193 PACKAGE_STRING=\"jp2a x.x.x-win32\"
194 PACKAGE_BUGREPORT=\"[email protected]\"
195 HAVE_STRING_H
196 HAVE_STDLIB_H
197 FEAT_CURL
198 HAVE_CURL_CURL_H
199 CURL_STATICLIB
200 FEAT_TERMLIB
201
202 You need to add jpeg.lib to the linker. If you want libcurl support, you need
203 that as well. It should be available from https://curl.haxx.se