From 785398ce4b62bc67acd68e4aee9422da771b8064 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ionic=C4=83=20Biz=C4=83u?= Date: Tue, 26 Apr 2016 08:03:09 +0300 Subject: [PATCH] Updated docs --- CONTRIBUTING.md | 4 ++- DOCUMENTATION.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 24 ++++++++++-------- 3 files changed, 80 insertions(+), 11 deletions(-) create mode 100644 DOCUMENTATION.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 765cef8..5bc7e12 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,6 +59,8 @@ Contributions are more than welcome! Thanks! :sweat_smile: + + [1]: https://github.com/IonicaBizau/image-to-ascii/issues -[2]: https://github.com/IonicaBizau/code-style \ No newline at end of file +[2]: https://github.com/IonicaBizau/code-style diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..e603b49 --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,63 @@ +## Documentation + +You can see below the API reference of this module. + +### `imageToAscii(source, options, callback)` +Converts the provided image in ASCII art. + +#### Params +- **String** `source`: The path/url to the image. +- **Object|String** `options`: The path to the image or an object containing the following fields: + + **Size Options**: + - `pxWidth` (Number): The pixel width used for aspect ratio (default: `2`). + - `size` (Object): The size of the result image (ASCII art)—interpreted by + [`compute-size`](https://github.com/IonicaBizau/compute-size): + - `height` (Number|String): The height value (default: `"100%"`). + - `width` (Number|String): The width value (default: computed value to + keep aspect ratio). This is optional if the height is provided. + - `size_options` (Object): The options for + [`compute-size`](https://github.com/IonicaBizau/compute-size): + - `screen_size` (Object): The screen size (defaults to terminal width + and height): + - `width` (Number): The screen width. + - `height` (Number): The screen height. + - `px_size` (Object): The pixel size. + - `width` (default: `1`) + - `height` (default: `1`) + - `preserve_aspect_ratio` (Boolean): If `false`, the aspect ratio will + not be preserved (default: `true`). + - `fit_screen` (Boolean): If `false`, the result size will not fit to + screen (default: `true`). + + **Matrix asciifier options**: + - `stringify` (Boolean): If `false`, the pixel objects will not be + stringified. + - `concat` (Boolean): If `false`, the pixel objects will not be joined + together. + + **Pixel asciifier options**: + + - `pixels` (Array|String): An array or string containing the characters + used for converting the pixels in strings + (default: `" .,:;i1tfLCG08@"`). + - `reverse` (Boolean): If `true`, the pixels will be reversed creating a + *negative image* effect (default: `false`). + - `colored` (Boolean): If `true`, the output will contain ANSI styles + (default: `true`). + - `bg` (Boolean): If `true`, the **background** color will be used for + coloring (default: false). + - `fg` (Boolean): If `true`, the **foreground** color will be used for + coloring (default: true). + - `white_bg` (Boolean): Turn on the white background for transparent + pixels (default: `true`). + - `px_background` (Object): An object containing the `r` (red), `g` + (green) and `b` (blue) values of the custom background color. + + **Other options**: + - `image_type` (String): Use this to explicitely provide the image type. + - `stringify_fn` (Function): A function getting the `pixels` matrix and + the `options` in the arguments. Use this option to implement your own + stringifier. +- **Function** `callback`: The callback function. + diff --git a/README.md b/README.md index 1ccda1f..cfed7b1 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + [![image-to-ascii](http://i.imgur.com/pKydY5P.png)](#) # image-to-ascii [![PayPal](https://img.shields.io/badge/%24-paypal-f39c12.svg)][paypal-donations] [![Version](https://img.shields.io/npm/v/image-to-ascii.svg)](https://www.npmjs.com/package/image-to-ascii) [![Downloads](https://img.shields.io/npm/dt/image-to-ascii.svg)](https://www.npmjs.com/package/image-to-ascii) [![Get help on Codementor](https://cdn.codementor.io/badges/get_help_github.svg)](https://www.codementor.io/johnnyb?utm_source=github&utm_medium=button&utm_term=johnnyb&utm_campaign=github) @@ -7,19 +8,19 @@ [![image-to-ascii](http://i.imgur.com/Om8G7dZ.png)](#) ## :cloud: Installation - + ```sh $ npm i --save image-to-ascii ``` - + :bulb: **ProTip**: You can install the [cli version of this module](http://github.com/IonicaBizau/image-to-ascii-cli) by running `npm i -g image-to-ascii-cli` - + Check out the [INSTALLTION.md](/INSTALLTION.md) guide for more information. ## :clipboard: Example - + ```js // Dependencies @@ -37,7 +38,7 @@ imageToAscii("https://octodex.github.com/images/privateinvestocat.jpg", { console.log(err || converted); }); ``` - + In order to run the `webcam.sh` provided in the `example` folder, you will also need streamer. The script uses streamer to make webcam pictures and converts them into ASCII art using the `webcam.js` @@ -53,7 +54,8 @@ sh webcam.sh ``` ## :memo: Documentation - + + ### `imageToAscii(source, options, callback)` Converts the provided image in ASCII art. @@ -113,22 +115,24 @@ Converts the provided image in ASCII art. stringifier. - **Function** `callback`: The callback function. - + + ## :yum: How to contribute Have an idea? Found a bug? See [how to contribute][contributing]. ## :dizzy: Where is this library used? If you are using this library in one of your projects, add it in this list. :sparkles: + - [`alphabet-cli`](https://github.com/joliveros/alphabet-cli#readme)—undefined - [`ascii-github`](https://npmjs.com/package/ascii-github)—GitHub CLI Client - [`cli-github`](https://github.com/IonicaBizau/cli-github)—A fancy GitHub client for command line. - - [`cli-sunset`](https://github.com/IonicaBizau/cli-sunset)—A fancy command line tool for knowing the sunset time. - [`doomjs`](https://github.com/codezilla-it/doom#readme) (by Fabio Cencetti)—A bunch of modular gulp tasks - [`gif-cli`](https://github.com/IonicaBizau/gif-cli)—Gif animations in your terminal! - [`ick`](https://github.com/nteract/ick#readme) (by Kyle Kelley)—Interactive Console Experiment - [`image-to-ascii-cli`](https://github.com/IonicaBizau/image-to-ascii-cli#readme)—View images in text format, in your terminal. - [`image-to-js`](https://github.com/xinyu198736/image-to-js#readme) (by yutou)—用js代码和图片，生成一段可以正常运行的图形化的js源代码 + - [`img-to-svg`](https://github.com/IonicaBizau/img-to-svg#readme)—Convert the image pixels in SVG squares. - [`imgurize`](https://github.com/mkaminsky11/imgurize) (by Michael Kaminsky)—an Imgur browser in the terminal - [`joctodex`](https://github.com/IonicaBizau/joctodex#readme)—Octocats in terminal! - [`js2image`](https://github.com/xinyu198736/image-to-js#readme) (by yutou)—用js代码和图片，生成一段可以正常运行的图形化的js源代码 @@ -138,9 +142,9 @@ If you are using this library in one of your projects, add it in this list. :spa - [`tmuxos`](https://github.com/TmuxOS/TmuxOS)—The awesome power of command line is finally revealed. ## :scroll: License - + [MIT][license] © [Ionică Bizău][website] - + [paypal-donations]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=RVXDDLKKLQRJW [donate-now]: http://i.imgur.com/6cMbHOC.png