{"_id":"@cofy-x/pixel-to-ascii","_rev":"2-5ef1531250268e14e38182344b92bda4","name":"@cofy-x/pixel-to-ascii","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@cofy-x/pixel-to-ascii","version":"0.1.0","keywords":["ascii","ansi","ascii-art","image","image-processing","cli","terminal","truecolor","nodejs","typescript"],"author":{"name":"wayne","email":"rcywjo@gmail.com"},"license":"Apache-2.0","_id":"@cofy-x/pixel-to-ascii@0.1.0","maintainers":[{"name":"rcyw","email":"rcywjo@gmail.com"}],"homepage":"https://github.com/cofy-x/pixel-to-ascii#readme","bugs":{"url":"https://github.com/cofy-x/pixel-to-ascii/issues"},"bin":{"pixa":"dist/cli.js"},"dist":{"shasum":"bcaf0090b03caf6d7044738b01a5b82678e5533b","tarball":"https://registry.npmjs.org/@cofy-x/pixel-to-ascii/-/pixel-to-ascii-0.1.0.tgz","fileCount":24,"integrity":"sha512-CP4RJ07gIuGwkzBeFG9EkuajaabY8yyLKtaSRK4KNJCuvgoPazIjHPmgKGmJpYpoCr1p7Q8gN1VL4gTwNhSHGQ==","signatures":[{"sig":"MEYCIQDrmKn+sZRwgt6s4syzqSxC95Q5gmVHT+iIuu9iSqC24AIhALsnEYxUMjhljradD4dkwUzZVCEEync51kYoX1sdn5Rn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cofy-x%2fpixel-to-ascii@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":43641},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"3699c98a9cfa7b0cf97eb776aba6ce7e190d9877","scripts":{"lint":"eslint .","test":"vitest run","build":"tsc -p tsconfig.build.json","check":"pnpm run lint && pnpm run test && pnpm run build && pnpm run package:check","start":"node dist/index.js","format":"prettier --experimental-cli --write .","dev:cli":"tsx src/cli.ts","prepack":"pnpm run build","cli:link":"pnpm run build && npm link","dev:demo":"tsx examples/demo.ts","lint:fix":"eslint . --fix","cli:unlink":"npm unlink -g @cofy-x/pixel-to-ascii","package:check":"publint && attw --pack --profile esm-only . && node ./scripts/verify-package.mjs","lint:fix:format":"pnpm run lint:fix && pnpm run format"},"_npmUser":{"name":"rcyw","email":"rcywjo@gmail.com"},"repository":{"url":"git+https://github.com/cofy-x/pixel-to-ascii.git","type":"git"},"_npmVersion":"11.16.0","description":"A lightweight, high-fidelity TypeScript library and CLI tool to convert images into ASCII art using ANSI TrueColor.","directories":{},"sideEffects":false,"_nodeVersion":"24.18.0","dependencies":{"jimp":"^1.6.1","chalk":"^5.6.2","commander":"^14.0.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.24.0","devDependencies":{"tsx":"^4.21.0","eslint":"^9.39.2","vitest":"^4.0.16","globals":"^17.0.0","publint":"^0.3.22","prettier":"^3.7.4","@eslint/js":"^9.39.2","typescript":"^5.9.3","@types/node":"^25.0.3","typescript-eslint":"^8.52.0","@vitest/coverage-v8":"^4.0.16","eslint-plugin-import":"^2.32.0","@arethetypeswrong/cli":"^0.18.5","@vitest/eslint-plugin":"^1.6.6","eslint-config-prettier":"^10.1.8","eslint-plugin-license-header":"^0.8.0"},"_npmOperationalInternal":{"tmp":"tmp/pixel-to-ascii_0.1.0_1785220753903_0.766815404443056","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@cofy-x/pixel-to-ascii","version":"0.2.0","description":"A lightweight, high-fidelity TypeScript library and CLI tool to convert images into ASCII art using ANSI TrueColor.","engines":{"node":">=20.0.0"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"bin":{"pixa":"dist/cli.js"},"sideEffects":false,"scripts":{"build":"tsc -p tsconfig.build.json","dev:demo":"tsx examples/demo.ts","dev:cli":"tsx src/cli.ts","start":"node dist/index.js","lint":"eslint .","lint:fix":"eslint . --fix","lint:fix:format":"pnpm run lint:fix && pnpm run format","test":"vitest run","check":"pnpm run lint && pnpm run test && pnpm run build && pnpm run package:check","package:check":"publint && attw --pack --profile esm-only . && node ./scripts/verify-package.mjs","prepack":"pnpm run build","format":"prettier --experimental-cli --write .","cli:link":"pnpm run build && npm link","cli:unlink":"npm unlink -g @cofy-x/pixel-to-ascii"},"keywords":["ascii","ansi","ascii-art","image","image-processing","cli","terminal","truecolor","nodejs","typescript"],"author":{"name":"wayne","email":"rcywjo@gmail.com"},"license":"Apache-2.0","homepage":"https://github.com/cofy-x/pixel-to-ascii#readme","repository":{"type":"git","url":"git+https://github.com/cofy-x/pixel-to-ascii.git"},"bugs":{"url":"https://github.com/cofy-x/pixel-to-ascii/issues"},"publishConfig":{"access":"public"},"packageManager":"pnpm@10.24.0","dependencies":{"chalk":"^5.6.2","commander":"^14.0.2","jimp":"^1.6.1"},"devDependencies":{"@arethetypeswrong/cli":"^0.18.5","@eslint/js":"^10.0.1","@types/node":"^25.9.5","@vitest/coverage-v8":"^4.1.10","@vitest/eslint-plugin":"^1.6.24","eslint":"^10.8.0","eslint-config-prettier":"^10.1.8","eslint-plugin-import-x":"^4.17.1","eslint-plugin-license-header":"^0.9.0","eslint-plugin-n":"^18.2.2","globals":"^17.8.0","prettier":"^3.9.6","publint":"^0.3.22","tsx":"^4.23.1","typescript":"^6.0.3","typescript-eslint":"^8.65.0","vite":"^8.1.5","vitest":"^4.1.10"},"gitHead":"f51518f6de98810e93e6e02f4e6bfb08d56d3c31","_id":"@cofy-x/pixel-to-ascii@0.2.0","_nodeVersion":"24.19.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-KwcWakozruP79JTvL473WpNlb+WN6sEpuAzNyCC00guX/TAx2WcObhHL5DF3r9GmBXKbyEv7v4OyyoK3FZB6pw==","shasum":"7fd846e490348208f8af3e131f793eb36d101c47","tarball":"https://registry.npmjs.org/@cofy-x/pixel-to-ascii/-/pixel-to-ascii-0.2.0.tgz","fileCount":24,"unpackedSize":55745,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cofy-x%2fpixel-to-ascii@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFrJ5zApTRAYAMuYRNg/XpeqX4SVfBF6FeQw70vd3T3BAiAUOJ5VGjJl+cxFQalgbru17VSs0D8VsxiuX1rie2Zdtg=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:30dbcc8e-a3c9-4204-af4d-3a24106c62d3"}},"directories":{},"maintainers":[{"name":"rcyw","email":"rcywjo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pixel-to-ascii_0.2.0_1787504725012_0.5065389387731734"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T06:39:13.585Z","modified":"2026-08-23T17:05:25.524Z","0.1.0":"2026-07-28T06:39:14.033Z","0.2.0":"2026-08-23T17:05:25.160Z"},"bugs":{"url":"https://github.com/cofy-x/pixel-to-ascii/issues"},"author":{"name":"wayne","email":"rcywjo@gmail.com"},"license":"Apache-2.0","homepage":"https://github.com/cofy-x/pixel-to-ascii#readme","keywords":["ascii","ansi","ascii-art","image","image-processing","cli","terminal","truecolor","nodejs","typescript"],"repository":{"type":"git","url":"git+https://github.com/cofy-x/pixel-to-ascii.git"},"description":"A lightweight, high-fidelity TypeScript library and CLI tool to convert images into ASCII art using ANSI TrueColor.","maintainers":[{"name":"rcyw","email":"rcywjo@gmail.com"}],"readme":"# Pixel-to-ASCII (`pixa`)\n\n[![npm version](https://img.shields.io/npm/v/@cofy-x/pixel-to-ascii)](https://www.npmjs.com/package/@cofy-x/pixel-to-ascii)\n[![CI](https://github.com/cofy-x/pixel-to-ascii/actions/workflows/ci.yml/badge.svg)](https://github.com/cofy-x/pixel-to-ascii/actions/workflows/ci.yml)\n[![Node.js](https://img.shields.io/node/v/@cofy-x/pixel-to-ascii)](https://nodejs.org/)\n[![License](https://img.shields.io/github/license/cofy-x/pixel-to-ascii)](./LICENSE)\n\nA lightweight TypeScript library and CLI for converting images into high-fidelity ANSI TrueColor art.\n\n`pixa` renders two vertical pixels with one half-block character (`▀` or `▄`). This preserves image proportions while producing compact, colorful terminal output.\n\n![Original abstract sunrise example](./examples/assets/sunrise.png)\n\n## Features\n\n- ANSI TrueColor output with separate foreground and background colors.\n- Half-block rendering for two pixels per terminal row.\n- Automatic cropping of transparent borders.\n- Configurable output width, resampling mode, and alpha threshold.\n- Local file, directory, and HTTP(S) URL inputs.\n- Exact, minimum, and maximum output-height filters.\n- Terminal output or reusable ANSI text files.\n- ESM TypeScript API and the `pixa` command-line tool.\n\n## Requirements\n\n- Node.js 20 or newer.\n- An ANSI TrueColor-compatible terminal for full-color output.\n- ESM for programmatic imports. CommonJS consumers can use dynamic `import()`.\n\n## CLI\n\nRun without installing:\n\n```sh\nnpx @cofy-x/pixel-to-ascii ./image.png\n```\n\nOr install globally:\n\n```sh\nnpm install --global @cofy-x/pixel-to-ascii\npixa --help\n```\n\nConvert one image, a directory, or an image URL:\n\n```sh\npixa ./image.png\npixa ./images/\npixa https://example.com/image.png\n```\n\nSave ANSI output to text files instead of printing it:\n\n```sh\npixa ./images/ --output ./output\n```\n\nSave and print at the same time:\n\n```sh\npixa ./image.png --output ./output --print\n```\n\nResize an image to a compact terminal width. Use nearest-neighbor scaling for\npixel art:\n\n```sh\npixa ./sprite.png --width 32 --pixelated --output ./output\n```\n\n### Options\n\n| Option                     | Alias | Description                                                         |\n| -------------------------- | ----- | ------------------------------------------------------------------- |\n| `--width <number>`         | `-w`  | Resize to this many terminal columns while preserving aspect ratio. |\n| `--pixelated`              |       | Use nearest-neighbor resizing with `--width`.                       |\n| `--alpha-threshold <n>`    |       | Treat alpha values below `n` (1–255, default 16) as transparent.    |\n| `--target-height <number>` | `-t`  | Keep results with exactly this terminal line count.                 |\n| `--min-height <number>`    | `-m`  | Keep results at or above this line count.                           |\n| `--max-height <number>`    | `-M`  | Keep results at or below this line count.                           |\n| `--output <path>`          | `-o`  | Save each result as an ANSI `.txt` file.                            |\n| `--print`                  | `-p`  | Print results even when `--output` is used.                         |\n| `--verbose`                | `-v`  | Report input discovery, skipped images, and processing failures.    |\n| `--help`                   | `-h`  | Show CLI help.                                                      |\n\nAn invalid local source exits with an error. Individual unreadable or unsupported images are skipped; enable `--verbose` to see those failures. A successful scan with no images matching the height filters is not an error.\n\n## Library\n\nInstall the package:\n\n```sh\nnpm install @cofy-x/pixel-to-ascii\n```\n\nImport the ESM API:\n\n```ts\nimport { generateAscii } from '@cofy-x/pixel-to-ascii';\n\nconst [result] = await generateAscii('./image.png');\n\nif (result) {\n  console.log(result.ascii);\n}\n```\n\nProcess a directory with output-height filters:\n\n```ts\nconst icons = await generateAscii('./images', {\n  minHeight: 8,\n  maxHeight: 16,\n  verbose: true,\n});\n```\n\n### `generateAscii(source, options?)`\n\n`source` is a local file path, a local directory, or an HTTP(S) URL. The function returns `Promise<AsciiResult[]>`.\n\n```ts\ninterface GenerateOptions {\n  width?: number;\n  pixelated?: boolean;\n  alphaThreshold?: number;\n  targetHeight?: number;\n  minHeight?: number;\n  maxHeight?: number;\n  verbose?: boolean;\n}\n\ninterface AsciiResult {\n  source: string;\n  ascii: string;\n  lineCount: number;\n  originalWidth: number;\n  originalHeight: number;\n}\n```\n\nWhen `targetHeight` is set, it takes precedence over `minHeight` and `maxHeight`. Per-image decoding failures are omitted from the returned array and reported only when `verbose` is enabled.\n\n`width` resizes the cropped image before rendering and preserves its aspect ratio. `pixelated` switches that resize to nearest-neighbor sampling and requires `width`. Pixels below `alphaThreshold` are cleared before cropping and rendering, preventing nearly invisible edge pixels from creating halos or extra blank rows. Generated `ascii` always contains ANSI TrueColor sequences, including when called from CI or redirected to a file. `originalWidth` and `originalHeight` continue to describe the decoded source image before cropping or resizing.\n\n## Used by pokefetch\n\n[`cofy-x/pokefetch`](https://github.com/cofy-x/pokefetch) uses `pixel-to-ascii` to prepare pre-colored ANSI terminal assets. Pokémon source artwork used by that separate project is third-party material and is not part of this package or covered by this project's Apache-2.0 license.\n\n## Development\n\n```sh\npnpm install\npnpm check\npnpm dev:demo\npnpm dev:cli ./examples/assets/sunrise.png\n```\n\n`pnpm check` runs linting, tests, TypeScript compilation, package metadata checks, ESM type-resolution checks, and an npm tarball contents audit.\n\nTo test the globally linked command:\n\n```sh\npnpm cli:link\npixa --help\npnpm cli:unlink\n```\n\n## Security and contributing\n\nBug reports and feature requests are welcome in [GitHub Issues](https://github.com/cofy-x/pixel-to-ascii/issues). Follow the cofy-x organization contribution and security policies; do not report vulnerabilities in public issues.\n\n## License\n\nCopyright © 2025 cofy-x.\n\nLicensed under the [Apache License 2.0](./LICENSE).\n","readmeFilename":"README.md"}