RomanNum3ral
/
ascii-image-converter
mirror of https://github.com/TheZoraiz/ascii-image-converter.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add html save option

This commit is contained in:
Kim Roelofs 2024-08-23 15:21:21 +02:00
parent c43a6fc8e9
commit 0abc4c0811
1 changed files with 32 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
README.md
View File

@ -11,13 +11,12 @@ ascii-image-converter is a command-line tool that converts images into ascii art
Now supports braille art! Now supports braille art!
Input formats currently supported: Input formats currently supported:
* JPEG/JPG
- JPEG/JPG * PNG
- PNG * BMP
- BMP * WEBP
- WEBP * TIFF/TIF
- TIFF/TIF * GIF
- GIF
<p align="center"> <p align="center">
<img src="https://raw.githubusercontent.com/TheZoraiz/ascii-image-converter/master/example_gifs/all.gif"> <img src="https://raw.githubusercontent.com/TheZoraiz/ascii-image-converter/master/example_gifs/all.gif">
@ -25,21 +24,21 @@ Input formats currently supported:
## Table of Contents ## Table of Contents
- [Installation](#installation) - [Installation](#installation)
- [Debian / Ubuntu-based](#debian-or-ubuntu-based-distros) * [Debian / Ubuntu-based](#debian-or-ubuntu-based-distros)
- [Homebrew](#homebrew) * [Homebrew](#homebrew)
- [AUR](#aur) * [AUR](#aur)
- [Scoop](#scoop) * [Scoop](#scoop)
- [Snap](#snap) * [Snap](#snap)
- [Go](#go) * [Go](#go)
- [Linux (binaries)](#linux) * [Linux (binaries)](#linux)
- [Windows (binaries)](#windows) * [Windows (binaries)](#windows)
- [CLI Usage](#cli-usage) - [CLI Usage](#cli-usage)
- [Flags](#flags) * [Flags](#flags)
- [Library Usage](#library-usage) - [Library Usage](#library-usage)
- [Contributing](#contributing) - [Contributing](#contributing)
- [Packages Used](#packages-used) - [Packages Used](#packages-used)
- [License](#license) - [License](#license)
## Installation ## Installation
@ -50,15 +49,12 @@ Execute the following commands in order:
``` ```
echo 'deb [trusted=yes] https://apt.fury.io/ascii-image-converter/ /' | sudo tee /etc/apt/sources.list.d/ascii-image-converter.list echo 'deb [trusted=yes] https://apt.fury.io/ascii-image-converter/ /' | sudo tee /etc/apt/sources.list.d/ascii-image-converter.list
``` ```
``` ```
sudo apt update sudo apt update
``` ```
``` ```
sudo apt install -y ascii-image-converter sudo apt install -y ascii-image-converter
``` ```
<br> <br>
To remove the package source (which means you won't be getting any further updates), execute this command: To remove the package source (which means you won't be getting any further updates), execute this command:
@ -72,11 +68,9 @@ sudo rm -v /etc/apt/sources.list.d/ascii-image-converter.list
### Homebrew ### Homebrew
Installation with homebrew is available for both Linux and macOS. Installation with homebrew is available for both Linux and macOS.
``` ```
brew install TheZoraiz/ascii-image-converter/ascii-image-converter brew install TheZoraiz/ascii-image-converter/ascii-image-converter
``` ```
[Link to homebrew repository](https://github.com/TheZoraiz/homebrew-ascii-image-converter) [Link to homebrew repository](https://github.com/TheZoraiz/homebrew-ascii-image-converter)
<hr> <hr>
@ -86,25 +80,19 @@ brew install TheZoraiz/ascii-image-converter/ascii-image-converter
The AUR repo is maintained by [magnus-tesshu](https://aur.archlinux.org/account/magnus-tesshu) The AUR repo is maintained by [magnus-tesshu](https://aur.archlinux.org/account/magnus-tesshu)
Standard way: Standard way:
``` ```
git clone https://aur.archlinux.org/ascii-image-converter-git.git git clone https://aur.archlinux.org/ascii-image-converter-git.git
``` ```
``` ```
cd ascii-image-converter-git/ cd ascii-image-converter-git/
``` ```
``` ```
makepkg -si makepkg -si
``` ```
AUR helper: AUR helper:
``` ```
<aur-helper> -S ascii-image-converter-git <aur-helper> -S ascii-image-converter-git
``` ```
<hr> <hr>
### Scoop ### Scoop
@ -119,14 +107,15 @@ scoop install ascii-image-converter
### Snap ### Snap
> **Note:** The snap will not have access to hidden files and files outside the $HOME directory. This includes write access for saving ascii art as well. > **Note:** The snap will not have access to hidden files and files outside the $HOME directory. This includes write access for saving ascii art as well.
``` ```
sudo snap install ascii-image-converter sudo snap install ascii-image-converter
``` ```
Visit [the app's snap store listing](https://snapcraft.io/ascii-image-converter) for instructions regarding enabling snapd on your distribution. Visit [the app's snap store listing](https://snapcraft.io/ascii-image-converter) for instructions regarding enabling snapd on your distribution.
[![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/ascii-image-converter) [![Get it from the Snap Store](https://snapcraft.io/static/images/badges/en/snap-store-black.svg)](https://snapcraft.io/ascii-image-converter)
<hr> <hr>
@ -136,7 +125,6 @@ Visit [the app's snap store listing](https://snapcraft.io/ascii-image-converter)
``` ```
go install github.com/TheZoraiz/ascii-image-converter@latest go install github.com/TheZoraiz/ascii-image-converter@latest
``` ```
<hr> <hr>
For physically installing the binaries, follow the steps with respect to your OS. For physically installing the binaries, follow the steps with respect to your OS.
@ -150,7 +138,6 @@ Now, open a terminal in the same directory and execute this command:
``` ```
sudo cp ascii-image-converter /usr/local/bin/ sudo cp ascii-image-converter /usr/local/bin/
``` ```
Now you can use ascii-image-converter in the terminal. Execute `ascii-image-converter -h` for more details. Now you can use ascii-image-converter in the terminal. Execute `ascii-image-converter -h` for more details.
### Windows ### Windows
@ -158,11 +145,10 @@ Now you can use ascii-image-converter in the terminal. Execute `ascii-image-conv
You will need to set an Environment Variable to the folder the ascii-image-converter.exe executable is placed in to be able to use it in the command prompt. Follow the instructions in case of confusion: You will need to set an Environment Variable to the folder the ascii-image-converter.exe executable is placed in to be able to use it in the command prompt. Follow the instructions in case of confusion:
Download the archive for your Windows architecture [here](https://github.com/TheZoraiz/ascii-image-converter/releases/latest), extract it, and open the extracted folder. Now, copy the folder path from the top of the file explorer and follow these instructions: Download the archive for your Windows architecture [here](https://github.com/TheZoraiz/ascii-image-converter/releases/latest), extract it, and open the extracted folder. Now, copy the folder path from the top of the file explorer and follow these instructions:
* In Search, search for and then select: Advanced System Settings
- In Search, search for and then select: Advanced System Settings * Click Environment Variables. In the section User Variables find the Path environment variable and select it. Click "Edit".
- Click Environment Variables. In the section User Variables find the Path environment variable and select it. Click "Edit". * In the Edit Environment Variable window, click "New" and then paste the path of the folder that you copied initially.
- In the Edit Environment Variable window, click "New" and then paste the path of the folder that you copied initially. * Click "Ok" on all open windows.
- Click "Ok" on all open windows.
Now, restart any open command prompt and execute `ascii-image-converter -h` for more details. Now, restart any open command prompt and execute `ascii-image-converter -h` for more details.
@ -177,19 +163,17 @@ The basic usage for converting an image into ascii art is as follows. You can al
``` ```
ascii-image-converter [image paths/urls] ascii-image-converter [image paths/urls]
``` ```
Example: Example:
``` ```
ascii-image-converter myImage.jpeg ascii-image-converter myImage.jpeg
``` ```
> **Note:** Piped binary input is also supported > **Note:** Piped binary input is also supported
>
> ``` > ```
> cat myImage.png | ascii-image-converter - > cat myImage.png | ascii-image-converter -
> ``` > ```
### Flags ### Flags
#### --color OR -C #### --color OR -C
@ -213,7 +197,6 @@ ascii-image-converter [image paths/urls] --color
> **Note:** Braille pattern display heavily depends on which terminal or font you're using. In windows, try changing the font from command prompt properties if braille characters don't display > **Note:** Braille pattern display heavily depends on which terminal or font you're using. In windows, try changing the font from command prompt properties if braille characters don't display
Use braille characters instead of ascii. For this flag, your terminal must support braille patters (UTF-8) properly. Otherwise, you may encounter problems with colored or even uncolored braille art. Use braille characters instead of ascii. For this flag, your terminal must support braille patters (UTF-8) properly. Otherwise, you may encounter problems with colored or even uncolored braille art.
``` ```
ascii-image-converter [image paths/urls] -b ascii-image-converter [image paths/urls] -b
# Or # Or
@ -229,7 +212,6 @@ ascii-image-converter [image paths/urls] --braille
Set threshold value to compare for braille art when converting each pixel into a dot. Value must be between 0 and 255. Set threshold value to compare for braille art when converting each pixel into a dot. Value must be between 0 and 255.
Example: Example:
``` ```
ascii-image-converter [image paths/urls] -b --threshold 170 ascii-image-converter [image paths/urls] -b --threshold 170
``` ```
@ -239,7 +221,6 @@ ascii-image-converter [image paths/urls] -b --threshold 170
Apply dithering on image to make braille art more visible. Since braille dots can only be on or off, dithering images makes them more visible in braille art. Apply dithering on image to make braille art more visible. Since braille dots can only be on or off, dithering images makes them more visible in braille art.
Example: Example:
``` ```
ascii-image-converter [image paths/urls] -b --dither ascii-image-converter [image paths/urls] -b --dither
``` ```
@ -251,7 +232,6 @@ ascii-image-converter [image paths/urls] -b --dither
#### --color-bg #### --color-bg
If any of the coloring flags is passed, this flag will transfer its color to each character's background. instead of foreground. However, this option isn't available for `--save-img` and `--save-gif` If any of the coloring flags is passed, this flag will transfer its color to each character's background. instead of foreground. However, this option isn't available for `--save-img` and `--save-gif`
``` ```
ascii-image-converter [image paths/urls] -C --color-bg ascii-image-converter [image paths/urls] -C --color-bg
``` ```
@ -261,19 +241,15 @@ ascii-image-converter [image paths/urls] -C --color-bg
> **Note:** Don't immediately append another flag with -d > **Note:** Don't immediately append another flag with -d
Set the width and height for ascii art in CHARACTER lengths. Set the width and height for ascii art in CHARACTER lengths.
``` ```
ascii-image-converter [image paths/urls] -d <width>,<height> ascii-image-converter [image paths/urls] -d <width>,<height>
# Or # Or
ascii-image-converter [image paths/urls] --dimensions <width>,<height> ascii-image-converter [image paths/urls] --dimensions <width>,<height>
``` ```
Example: Example:
``` ```
ascii-image-converter [image paths/urls] -d 60,30 ascii-image-converter [image paths/urls] -d 60,30
``` ```
<p align="center"> <p align="center">
<img src="https://raw.githubusercontent.com/TheZoraiz/ascii-image-converter/master/example_gifs/dimensions.gif"> <img src="https://raw.githubusercontent.com/TheZoraiz/ascii-image-converter/master/example_gifs/dimensions.gif">
</p> </p>
@ -283,15 +259,12 @@ ascii-image-converter [image paths/urls] -d 60,30
> **Note:** Don't immediately append another flag with -W > **Note:** Don't immediately append another flag with -W
Set width of ascii art. Height is calculated according to aspect ratio. Set width of ascii art. Height is calculated according to aspect ratio.
``` ```
ascii-image-converter [image paths/urls] -W <width> ascii-image-converter [image paths/urls] -W <width>
# Or # Or
ascii-image-converter [image paths/urls] --width <width> ascii-image-converter [image paths/urls] --width <width>
``` ```
Example: Example:
``` ```
ascii-image-converter [image paths/urls] -W 60 ascii-image-converter [image paths/urls] -W 60
``` ```
@ -301,15 +274,12 @@ ascii-image-converter [image paths/urls] -W 60
> **Note:** Don't immediately append another flag with -H > **Note:** Don't immediately append another flag with -H
Set height of ascii art. Width is calculated according to aspect ratio. Set height of ascii art. Width is calculated according to aspect ratio.
``` ```
ascii-image-converter [image paths/urls] -H <height> ascii-image-converter [image paths/urls] -H <height>
# Or # Or
ascii-image-converter [image paths/urls] --height <height> ascii-image-converter [image paths/urls] --height <height>
``` ```
Example: Example:
``` ```
ascii-image-converter [image paths/urls] -H 60 ascii-image-converter [image paths/urls] -H 60
``` ```
@ -320,16 +290,14 @@ ascii-image-converter [image paths/urls] -H 60
Pass a string of your own ascii characters to map against. Passed characters must start from darkest character and end with lightest. There is no limit to number of characters. Pass a string of your own ascii characters to map against. Passed characters must start from darkest character and end with lightest. There is no limit to number of characters.
Empty spaces can be passed if string is passed inside quotation marks. You can use both single or double quote for quotation marks. For repeating quotation mark inside string, append it with \ (such as \\"). Empty spaces can be passed if string is passed inside quotation marks. You can use both single or double quote for quotation marks. For repeating quotation mark inside string, append it with \ (such as \\").
``` ```
ascii-image-converter [image paths/urls] -m "<string-of-characters>" ascii-image-converter [image paths/urls] -m "<string-of-characters>"
# Or # Or
ascii-image-converter [image paths/urls] --map "<string-of-characters>" ascii-image-converter [image paths/urls] --map "<string-of-characters>"
``` ```
Following example contains 7 depths of lighting. Following example contains 7 depths of lighting.
``` ```
ascii-image-converter [image paths/urls] -m " .-=+#@" ascii-image-converter [image paths/urls] -m " .-=+#@"
``` ```
@ -365,7 +333,6 @@ ascii-image-converter [image paths/urls] --negative
#### --complex OR -c #### --complex OR -c
Print the image with a wider array of ascii characters for more detailed lighting density. Sometimes improves accuracy. Print the image with a wider array of ascii characters for more detailed lighting density. Sometimes improves accuracy.
``` ```
ascii-image-converter [image paths/urls] -c ascii-image-converter [image paths/urls] -c
# Or # Or
@ -375,7 +342,6 @@ ascii-image-converter [image paths/urls] --complex
#### --full OR -f #### --full OR -f
Print ascii art that fits the terminal width while maintaining aspect ratio. Print ascii art that fits the terminal width while maintaining aspect ratio.
``` ```
ascii-image-converter [image paths/urls] -f ascii-image-converter [image paths/urls] -f
# Or # Or
@ -393,7 +359,6 @@ ascii-image-converter [image paths/urls] -x
``` ```
#### --flipY OR -y #### --flipY OR -y
Flip the ascii art vertically on the terminal. Flip the ascii art vertically on the terminal.
``` ```
@ -402,6 +367,8 @@ ascii-image-converter [image paths/urls] --flipY
ascii-image-converter [image paths/urls] -y ascii-image-converter [image paths/urls] -y
``` ```
#### --save-img OR -s #### --save-img OR -s
> **Note:** Don't immediately append another flag with -s > **Note:** Don't immediately append another flag with -s
@ -497,7 +464,6 @@ ascii-image-converter --formats
> **Note:** The library may throw errors during Go tests due to some unresolved bugs with the [consolesize-go](https://github.com/nathan-fiscaletti/consolesize-go) package (Only during tests, not main program execution). > **Note:** The library may throw errors during Go tests due to some unresolved bugs with the [consolesize-go](https://github.com/nathan-fiscaletti/consolesize-go) package (Only during tests, not main program execution).
First, install the library with: First, install the library with:
``` ```
go get -u github.com/TheZoraiz/ascii-image-converter/aic_package go get -u github.com/TheZoraiz/ascii-image-converter/aic_package
``` ```
@ -542,7 +508,6 @@ func main() {
fmt.Printf("%v\n", asciiArt) fmt.Printf("%v\n", asciiArt)
} }
``` ```
<br> <br>
> **Note:** GIF conversion is not advised as the function may run infinitely, depending on the GIF. More work needs to be done on this to make it more library-compatible. > **Note:** GIF conversion is not advised as the function may run infinitely, depending on the GIF. More work needs to be done on this to make it more library-compatible.