| 1 |
jp2a |
| 2 |
==== |
| 3 |
|
| 4 |
 |
| 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 |