{"id":13456911,"url":"https://github.com/FineFindus/artem","last_synced_at":"2025-03-24T11:32:01.601Z","repository":{"id":40462677,"uuid":"459321714","full_name":"FineFindus/artem","owner":"FineFindus","description":"Convert images from multiple formats (jpg, png, webp, etc…) to ASCII art, written in Rust","archived":false,"fork":false,"pushed_at":"2024-03-28T10:52:37.000Z","size":9108,"stargazers_count":292,"open_issues_count":1,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-25T09:26:09.243Z","etag":null,"topics":["ascii","ascii-art","ascii-graphics","cli","command-line","command-line-tool","rust","terminal"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FineFindus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-02-14T20:51:34.000Z","updated_at":"2024-10-11T22:13:52.000Z","dependencies_parsed_at":"2024-01-07T21:02:35.231Z","dependency_job_id":"1fac338c-176a-4c5e-ba87-0be88bbc4496","html_url":"https://github.com/FineFindus/artem","commit_stats":{"total_commits":206,"total_committers":3,"mean_commits":68.66666666666667,"dds":0.009708737864077666,"last_synced_commit":"fea974cb8818190767b4623e51c7b96b492bbf7f"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FineFindus%2Fartem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FineFindus%2Fartem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FineFindus%2Fartem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FineFindus%2Fartem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FineFindus","download_url":"https://codeload.github.com/FineFindus/artem/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221962483,"owners_count":16908339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ascii","ascii-art","ascii-graphics","cli","command-line","command-line-tool","rust","terminal"],"created_at":"2024-07-31T08:01:29.926Z","updated_at":"2024-10-29T00:31:33.206Z","avatar_url":"https://github.com/FineFindus.png","language":"HTML","readme":"[![artem crate](https://img.shields.io/crates/v/artem.svg)](https://crates.io/crates/artem)\n![Terminal](https://badgen.net/badge/icon/terminal?icon=terminal\u0026label)\n[![Continuous Integration](https://github.com/FineFindus/artem/actions/workflows/continuous_integration.yaml/badge.svg)](https://github.com/FineFindus/artem/actions/workflows/continuous_integration.yaml)\n![maintenance-status](https://img.shields.io/badge/maintenance-passively--maintained-yellowgreen.svg)\n[![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)\n\n\u003c!-- https://gist.github.com/taiki-e/ad73eaea17e2e0372efb76ef6b38f17b --\u003e\n\n# Artem\n\nArtem is a small cli program, written in rust, to easily convert images\nto ascii art, named after the latin word for art. By default it tries to use truecolor, if the terminal does not support truecolor, it falls back to 16 Color ANSI. When the ascii image is written to a file, the image will not use colors.\nIt supports `.jpeg`, `.png`, `.gif`, `.webp` and many more.\n\nIf you want to use this project as a library, please refer to the [docs](https://docs.rs/artem/latest/artem/).\n\n## Maintenance\n\n#### **Is this project still being maintained?**\n\nYes. Although there is currently no active development of new features, issue and new feature request will still be worked on. If you have any issue or have an idea for a new feature, please [create an issue](https://github.com/FineFindus/artem/issues/new/choose).\n\n## Examples\n\n### Input\n\n_source:_ https://upload.wikimedia.org/wikipedia/commons/4/44/Abraham_Lincoln_head_on_shoulders_photo_portrait.jpg\n![Abraham Lincoln](/examples/abraham_lincoln.jpg)\n\n### Output\n\n![Abraham Lincoln](/examples/abraham_lincoln_ascii.png)\n\n## Usage\n\nFor simply converting an image:\n\n```bash\nartem path\n```\n\nThe input can either be one or multiple file paths or URLs.\n\n**NOTE**: To use URLs, the `web_image` feature has to be enabled. It is enabled by default.\n\nFor more options use:\n\n```bash\nartem --help\n```\n\nTo use custom ascii chars, use the `--characters` (or `-c` for short) argument.The characters should be ordered from darkest/densest to lightest.\nIf the background should be invisible, add a space at the end. Alternatively this program has already 3 predefined character sets,\naccessibly by supplying the `--characters` argument to gether with the number (`0`, `1` or `2`) of the preset that should be used.\nBy default preset `1` is used.\n\n```bash\nartem PATH --characters \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789\u003c\u003e|,.-#+!$%\u0026/()=?*'_:; \"\n```\n\nTo change the size at which the converted image is displayed, use:\n\n```bash\n#for auto sizing height\nartem PATH --height\n#for auto-sizing width\nartem PATH --width\n#for manual resizing use the --size flag\nartem PATH --size 100\n```\n\nIt is also possible to center the image using:\n\n```bash\n#center the image horizontally\nartem PATH --centerX\n#center the image vertically\nartem PATH --centerY\n```\n\nTo save the the image to a file, use the `--output` flag.\n\n```bash\nartem PATH --output ascii.txt\n#if the output file is an html file, the resulting ascii art will be saved as html ascii art, which supports colors\nartem PATH --output ascii.html\n# or alternatively, use an .asn file for colored ascii text\nartem PATH --output ascii.ans\n```\n\nUsing the `--outline` flag, the given input image will be filtered, to only contain an outline, which will then be converted. Please be aware, that this will take some additional time, as well as that it might not perfectly work on every image. For the best result, please use an image with a clear distinction between the background and the foreground.\n\n```bash\nartem PATH --outline\n```\n\nFor an even better result, it might be worthwhile trying out the `--hysteresis`/`--hys` flag, potentially with characters better suited for outlines, for example.\n\n```bash\nartem PATH --outline --hysteresis --characters \"|/\\_.  \"\n```\n\n## Installation\n\n### All platforms (recommended)\n\nThe easiest way to install artem is using `cargo` with\n\n```bash\ncargo install artem\n```\n\nIt will automatically add `artem` to your PATH variable, so it can used like shown in the [usage section](#usage).\n\nIf `cargo` is not installed, visit the [cargo book](https://doc.rust-lang.org/cargo/getting-started/installation.html) for installation instructions.\n\n### Linux\n\n#### Debian-based Distributions (e.g. Ubuntu)\n\nFor Debian-based Distributions, like Ubuntu, download the `.deb` file from the [release](https://github.com/FineFindus/artem/releases) page and install it with:\n\n```bash\nsudo dpkg -i artem.deb\n```\n\nThe `.deb` package also contains tab completions (for bash, zsh and fish) and a man page.\n\n#### Archlinux-based Distributions\n\n`artem` is available as an AUR package. You can install it with your favorite aur-helper, for example with `yay`:\n\n```bash\nyay -S artem\n```\n\nThis will build it from source.\nAlternatively, it is also available as a precompiled binary (`artem-bin`):\n\n```bash\nyay -S artem-bin\n```\n\n#### Other Distributions\n\nOn other distributions use the binary file provided in the [release tab](https://github.com/FineFindus/artem/releases).\n\nAlternatively, if `brew` is installed, you can also use `brew` to install it. See the [MacOS Homebrew section](#using-homebrew) for more information.\n\n### MacOS\n\n#### Using Homebrew\n\n\u003e **Warning**\n\u003e It's no longer recommended to install `artem` via Homebrew, as the tap is no longer maintained due to difficulty working with Homebrew. If you wish to maintain the tap, please contact me.\n\n```bash\nbrew install finefindus/tap/artem\n```\n\nThe homebrew version has the added benefit of also installing the man page and tab completions for bash, zsh and fish.\n\n#### Binary files\n\nAlternatively binary files (for x86_64 and Arm) are provided in the [release tab](https://github.com/FineFindus/artem/releases). This way of installing is NOT recommend over using [`cargo`](#all-platforms-recommended).\n\n### Windows\n\nTo install the windows version, without using `cargo`, download either the gnu- or the mscv compiled `.zip` files from [release tab](https://github.com/FineFindus/artem/releases) and extract the `.exe`. It should be noted that you will have to add the `.exe` manually to the PATH variable.\n\n## Shell completions\n\n`artem` has shell completions and a man page available. When using the homebrew version, the `.deb` package, or the aur versions, they are installed automatically, whilst for using the binary files with shell completions, the completion files, which be can be found in the compressed release file, have to be copied to the correct locations.\nAssuming the compressed file has been uncompressed, use following commands to copy the files to their correct location for unix-like systems:\n\n### Shell Completions and Man page\n\nFor **bash**:\n\n```bash\n#copy the bash completion file\nsudo cp completions/artem.bash  /etc/bash_completion.d/\n```\n\nFor **zsh** add the file to a `$fpath` directory:\n\n```zsh\n#copy the zsh completion file\ncp completions/_artem $fpath\n```\n\nFor **fish** add the file to the fish completions directory:\n\n```fish\n#copy the fish completion file\ncp completions/artem.fish $HOME/.config/fish/completions/\n```\n\nFor Windows add `. /path/to/_artem.ps1` (including the dot) to the PowerShell [profile](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.2).\n\n### Man Page\n\n`artem` also provides a man page for the binary releases contained in the `doc` directory. To view it using the `-l` flag for `man` to view a local file.\n\n```bash\n#view the local man page\nman -l doc/artem.1\n```\n\n## Building from source\n\nAssuming you have rust/cargo installed, you can build the project with:\n\n```bash\ncargo build --release\n```\n\nThe `--release` flag disables debugging options, increasing performance.\n\nVisit the [rust homepage](https://www.rust-lang.org/learn/get-started) for installation instructions if rust is not installed.\n\n### Features\n\nThis disables the default features, whilst enabling all other specified features:\n\n```bash\ncargo build --release --no-default-features --features FEATURES\n```\n\nFor more information about the usage of features, please refer to the [cargo book](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options).\n\nThe following features are currently available:\n\n- `web_image` Accept Image URLs as input (enabled by default)\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please be aware that it might take some time for someone to respond.\n\n## Credits/Inspiration\n\nThis projects was heavily inspired by [jp2a](https://github.com/cslarsen/jp2a) as well as\nthe [coding train video on ascii art](https://www.youtube.com/watch?v=55iwMYv8tGI).\n\nAlso a big thanks to [ripgrep](https://github.com/BurntSushi/ripgrep/) for indirectly helping with inspiration for the build setup.\n\nThe following images are used for testing/examples:\n\n- [Abraham Lincoln](https://upload.wikimedia.org/wikipedia/commons/4/44/Abraham_Lincoln_head_on_shoulders_photo_portrait.jpg)\n- [Radio tower](https://unsplash.com/photos/hDXk9iOi9bM)\n- [Moth](https://altphotos.com/photo/deaths-head-hawkmoth-3464/)\n\n## Todo\n\n- [x] Better average the RGB values of multiple pixel\n\n- [x] Use the current terminal size to auto fit the image\n\n- [x] Support ANSI terminal colors\n\n- [x] Convert output to colored html\n\n- [x] Use multithreading\n\n- [x] Add tests\n\n- [x] Add even more test\n\n- [x] Convert multiple files at once\n\n- [x] Automate copying of completion files from OUT_DIR to deployment/assets\n\n- [x] Change name\n\n- [x] Publish\n\n### Potential Ideas\n\n- [x] Use edge detection and directional ascii\n\n- [ ] Implement better resizing\n\n## License\n\n[Mozilla Public License 2.0.](LICENSE)\n","funding_links":[],"categories":["\u003ca name=\"graphics\"\u003e\u003c/a\u003eGraphics","HTML","Generators \u0026 Converters"],"sub_categories":["Imported: Upstream Snippet Gallery"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFineFindus%2Fartem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFineFindus%2Fartem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFineFindus%2Fartem/lists"}