imgtotext
v1.2.3
Published
ImgToText is a concise library that converts any image/video into customizable text!
Maintainers
louis-charles_bironReadme
ImgToText
ImgToText is a concise library that converts any image/video into custom text
This library makes your website able to generate live text conversions of pretty much any given media, and thus can be used to create some pretty interesting effects!
And if you don't know much about code and only want to use the converted text, you can check out this simple web interface!
.oXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=
OMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM-
XMMM~........................................OMMM~
XMMM- .~++~. OMMM~
XMMM- :HMMMMM- OMMM~ MMMMMMMM MMMMMMMMMM
XMMM- -MMMMMM= OMMM~ MMMMMMMMM MMMMMMMMMM
XMMM- -oXXO~ OMMM~ MMM MMMMMMMM MMMMMMMMMM MMMMMMM MMM MMMMMMMMMMM MMMMMMMMMM
XMMM- +O: OMMM~ MMMMM MMMMMMMMMM MMMMMMMMMMM MMMMMMMMMM MMM MMMMMMMMMMM MMMMMMMMMMM
XMMM- +HMMMX= OMMM~ MMMMMMMM MMM MMM MMM MMM MMM MMM MMM MMM MMMM MMM MM MMM MMMM
XMMM- =MMMMMMMMMo. .+XMX=. OMMM~ MMMMMM MMMM MMM MM MM MMM MMMMMMMMMM MMM MMM MM MM MMMMMMMMM
XMMM-.=HMMMMMMMMMMMMX- -oHMMMMMMMX=. OMMM~ MMM MMM MMM MM MM MMM MMM MMM MMM MM MM MMMMMMMMM
XMMMoMMMMMMMMMMMMMMMMMH=..~OMMMMMMMMMMMMMMX=.OMMM~ MMM MMMMM MMMMMMMMMM MM MM MMM MMMMMMMMMM MMM MMM MM MM MMMMMM
XMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM~ MMMMMMMMM MMMMMMMM MM MM MMM MMMMMMMMM MMMMMMMMMM MMM MM MM MMMMMMMMMM
XMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM~ MMM MMMMM
XMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM~ MMMMMMMMMM
XMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM~ MMMMMMMMM
XMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM~
XMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM~
OMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMM-
.oHMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMMHX= Table of Contents
Getting Started
- Get the library file. (
npm install imgtotextor imgToText.min.js)
<!-- Only if you're using the browser version! Otherwise use: import {ImageToTextConverter} from "imgtotext" -->
<script src="imgToText.min.js"></script>- In a JS file, create a new ImageToTextConverter instance.
// Converts the image ("someImg.png") and logs it in the console
const converter = new ImageToTextConverter((text)=>console.log(text), "someImg.png")ImageToTextConverter
The ImageToTextConverter class allows the full conversion and customization of images/videos to text.
The constructor takes the following parameters:
- new ImageToTextConverter(resultCB, sourceMedia?, pxGroupingSize?, charSet?, useColors?, maxMediaInputSize?, maxRefreshRate?)
resultCB -> A callback called on each conversion, its only parameter is the text result of the latest conversion.
(text)=>{...}sourceMedia? -> The image/video to convert. One of
ImageDisplay.SOURCE_TYPES.pxGroupingSize? -> The pixel output resolution. E.g.:
1converts pixels to characters at a 1:1 ratio (one character per media pixel), and5converts pixels to characters at a 25:1 ratio (one character per 5x5 pixels of the original media). Defaults to5.charSet? -> The characters used to draw the image using text, going from least visible to most visible. Either a
Stringor anArray. Defaults to[" ", ".", ":", "-", "~", "=", "+", "o" , "O" , "X", "H", "M"].useColors? -> Whether to color the generated text or keep it the default environment color (This uses HTML to render colors and thus can be VERY performance heavy).
colorOptimizationLevel -> Defines the color tolerance (0..255) for character grouping optimizations when using colors. If
falseornull, disables the character grouping optimizations.maxMediaInputSize? -> The canvas or canvas size on which media will be drawn. Either a size array
[width, height], aHTMLCanvasElement(to see medias before conversion), aOffscreenCanvas, or a CDEJSCanvas. Defaults to about[3840, 2160].maxRefreshRate? -> The aimed conversions per second (mostly for videos). Defaults to
30fps.
Note: - Putting null as any parameter value will assign it the default value of this parameter, if any. (Also applicable to most functions)
To load a new media use the loadMedia function:
- loadMedia(sourceMedia, size?, croppingPositions?, errorCB?, readyCB?)
// Loading and converting a new image
converter.loadMedia(
"someImg.png", // The media path
[100, 100], // The rendered size of the media
[[0,0], ["50%", "100%"]] // Cropping to only use the left half of the media
()=>console.log("Image loaded!"), // Callback called upon media load
()=>console.warn("Error loading image!")// Callback called upon error loading media
) // Loading and converting the live camera feed
converter.loadMedia(ImageDisplay.loadCamera())To format the text output of a conversion use the static formatText function:
- formatText(text, outputFormatingMethod?)
// A dummy converter
const converter = new ImageToTextConverter((text)=>{
// Regular output (raw)
console.log(text)
// Adapts the output to properly render in a Markdown environment (no colors)
console.log(ImageToTextConverter.formatText(text), ImageToTextConverter.OUTPUT_FORMATS.MARKDOWN_COLORLESS)
// Adapts the output to properly render in an HTML environment
console.log(ImageToTextConverter.formatText(text), ImageToTextConverter.OUTPUT_FORMATS.HTML)
})To force a conversion use the generate function:
- generate()
// Updating the characters used for conversion
converter.charSet = ImageToTextConverter.DEFAULT_CHARACTER_SETS.MIDDLE
// Forcing a new conversion to use the newly updated characters
converter.generate()To create/transform an HTML file input that loads and converts medias automatically use the createHTMLFileInput function:
- createHTMLFileInput(id?, onInputCB?)
// Creating an automated HTML file input
const fileInput = converter.createHTMLFileInput()
// Adding it to the DOM
document.body.appendChild(fileInput) // Accessing an already existing file input in the DOM
const existingFileInput = document.getElementById("myFileInput")
// Transforming it into an automated ImgToText file input
converter.createHTMLFileInput(existingFileInput)Visual Examples
Converting an image:
++++ooooooooooo++ooooooooooooooooooooooooooooo~::~+ooooooooooooooooooooooooooooooo++
++ooooOoooOooooooO~-::::::::::::::::::::::::. ~=: .:::::::::::::::::--=++OXOOOOOoo+
++ooo .:. +oooO~:..................... :=oooo+-. ...................-~+OXOOOoo
++ooo .- .+ooo+~.................... ~+ooooooooo=: ..................:~+OOoo+
++ooo - =oo+~:.................. :=ooooooooooooooo-. ..................:~Oo++
+++oo+~~=o+~~++=-:................ ~+ooooooooooooooooooo=: .......::::......-=o++
++++++oooo++=~-:::::::::::::::.. :=ooooooooo=--+oooooooooooo-. .::.::::::::::-~O++
+oo+===~---:::::::::::::::::: ~+ooooooooo~..~~.:=oooooooooooo=: .:::::::::::-~O++
+o+~::::::::::::::::::::::. :=ooooooooo+- -+OOOO+- -+oooooooooooo-. .:::::::::-=O++
+o+~:::::::::::--:::::::. ~+ooooooooooo=:.-oOOOOo-.-=oooo+:~ooooooo=: .::::::-=O++
+o+~:::::::::::---:::. :=ooooooooooooooooo-.:==:.~oooo+~.:~: -+ooooooo-. .::::-=O++
oo+~--------------:. ~+ooooooooo~: :=ooooooo=:-=oooo+: -=+oo+~.:~ooooooo=: :-~=Ooo
ooo~------------: :+ooooooooo+-.-+o+-.-+oooooooooo~.:=oooooo+=- -+ooooooooo-. :~Ooo
ooo=----------. ~oooooooooo+: ~oOOOOoo~ :oooooo+: -+ooooooo~..~oooooooooooooo=: :=o
+o+~:--------- -+oooooooooooo~.:=ooo=:.~ooooo~.:=ooooooo=- -+ooooooooooooooo++~. :~
+o+~::::::::---:. .~oooooooooooo=:.:.-=oooo+- -+ooooooo~..~oooooooo+++++++++=: .==+
+o+~:::::::::::---. -=++++oooooooo~ooooo~.:=ooooooo=- -+++++++++++++++++=-. .:~O++
+o+~::::::::::----::: .-+++++++++++++=: -=ooooooo~..~+++++++++++++++++=: ..::-~O++
+o+~:::::::-~~----:::::. -=+++++++++. -++ooooo=- -+++++++++++++++++=-. .:::::-~O++
+o+~-------=MMo~---------: .-++++++++~.:=+++~..~+++++++++++++++++=: .:--------~O++
+o+~-----~oM~.HX=-----------. :=+++++++=: : -+++++++++++++++++=-. .-----------~O++
+o+~-----OH: OH=------------:. .-++++++++~+++++++++++++++++=: .::-~~~~-------~O++
+o+~---~XX. +M+--------------. :=++++++++++++++++++++=-. .:----~~~~------~~O++
+o+~--=Ho -Mo---------------:. .-++++++++++++++++=: .:-------~~~--------~O++
+o+~-+M= :HX~----------------. :~++++++++++=-. :----------~~~~------~~O++
+o+~OM-............:OH=-----------------:. .-++++++=: .:------------~~~~------~~O++
+++=H-:::::::::::::::oM+~------------------. :~=-. :---------------~~~~------~~O++
+++~-::::::::::---::::=Mo~-------------------:. .:-----------------~~~~------~=O++
++O~+oooooooooOOOOOOOOOXMO======================~~~=====================~~~~~~~~o+++
+++o~~~~~~~~~~~===~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~===~~~~~~~~~~~===~~~~~~~oo+++
++++o+~~~~~~~~~==~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~===~~~~~~~~~~~===~~~~~+oooo++
++++++o++=~~~~~==~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~===~~~~~~~~~~~===~=+oooooo+++
++++++++++oo+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++oo+++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++Or with colors:
Settings used:
- Media width: 100%
- Media height: 40%
- Pixel Grouping Size: 3x3
- Character set (Default): [ " ", ".", ":", "-", "~", "=", "+", "o", "O", "X", "H", "M" ]
JS code:
// Creating a default ImageToTextConverter
new ImageToTextConverter(
(text)=>{console.log(text)}, // resultCB: function called upon a conversion, here simply logging to the console
"https://static.wikia.nocookie.net/logopedia/images/4/41/Geometry_Dash_Icon.svg", // sourceMedia: the source of the image to convert
3 // pxGroupingGroup: grouping pixels 3x3
)Converting some text
"cdejs"
MMMMMMMM MMMMMMMM MMMMMMMMM MMMMMMMM MMMMMMMM
MMMMMMMMMM MMMMMMMMMM MMMMMMMMM MMMMMMMM MMMMMMMMM
MMMM MMM MMMM MMM MMM MMM
MMMM MMM MMMM MMM MMM MMMMMM
MMMM MMM MMM MMMMMMMM MMM MMMMMMMM
MMMM MMM MMMM MMM MMM MMMMMM
MMM MMM MMMM MMM MMM MMM
MMMMM MM MMM MMMMMM MMM MM MMMM MM MMMM
MMMMMMMMM MMMMMMMMM MMMMMMMMM MMMMMMM MMMMMMMMMM
MMMMMM MMMM MMMMMMSettings used (All defaults):
- Text scale-x: 2
- Text scale-y: 1.25
- Pixel Grouping Size: 5x5
- Character set: [ " ", ".", ":", "-", "~", "=", "+", "o", "O", "X", "H", "M" ]
- Font: 54px monospace
JS code:
// Creating a default ImageToTextConverter and loading the text "CDEJS" to be converted
new ImageToTextConverter((text)=>{console.log(text)}, "CDEJS")Converting a video:
Settings used:
- Media width: 100%
- Media height (Default): 45%
- Pixel Grouping Size: 3x3
- Character set (Default): [ " ", ".", ":", "-", "~", "=", "+", "o", "O", "X", "H", "M" ]
JS code:
// Creating an ImageToTextConverter with a pixel grouping size of 3
const converter = new ImageToTextConverter((text)=>console.log(text), null, 3)
// Loading the video to be converted with a specific size
converter.loadMedia("./img/exampleRaw.mp4", ["100%", "45%"])Npx Commands
Here is the list of available npx commands:
To access all imgtotext commands remotely / other utility commands:
Use: npx imgtotext <commandName> <params?>
This is the global imgtotext command. It provides access to all regular imgtotext commands and some more. It also provides basic command autocompletion upon receiving an incomplete command name.
Example use 1:
Creating a project template using the imgtotext-template command. (see below for more details)
npx imgtotext template myProjectName
Example use 2:
Lists all available imgtotext commands. (As well as aliases)
npx imgtotext list
To create a template page
npx imgtotext-template <projectName?> | npx imgtotext-t <projectName?>
This command creates a modular ImgToText template page. It accepts an optional project name as parameter.
To create a browser template page
npx imgtotext-browser-template <projectName?> | npx imgtotext-bt <projectName?>
This command creates a non-modular ImgToText template page. It accepts an optional project name as parameter.
Optimization
To keep the best performance on your website/app, you may want to use some optimization techniques.
If performances become a concern:
Lower the media size. The media size is the most impactful on performance, so make sure the converted media is not unnecessarily big.
Try to avoid using colors (especially with high frequency conversions, such as videos)
When using colors, try to make the color optimization level higher. This will try to group characters by color with the defined level of tolerance. This greatly helps to reduce the amount of HTML elements required to render the text, which in turn improves performance.
Lower the max framerate. Having an unnecessarily high framerate when converting videos or any dynamic media is heavy on performances. Prioritise a smaller, but consistent framerate, rather than a higher but unreachable framerate.
Make the pixel grouping size higher. This can help a bit with improving performances, but comes at the cost of image precision.
Notes
This library is fully compatible with the CDEJS library and accepts canvas instances as media input.
Credits
Made by Louis-Charles Biron !
