{"id":13561092,"url":"https://github.com/duniul/pixel-scale","last_synced_at":"2025-07-20T03:31:20.314Z","repository":{"id":41424719,"uuid":"292944108","full_name":"duniul/pixel-scale","owner":"duniul","description":"📐 Get the pixel scale of an image, or scale it up or down without quality loss. Useful for pixel art!","archived":false,"fork":false,"pushed_at":"2024-05-13T08:01:10.000Z","size":582,"stargazers_count":20,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-17T20:16:56.657Z","etag":null,"topics":["canvas","image","image-processing","image-resize","imagedata","pixel-art","pixels"],"latest_commit_sha":null,"homepage":"https://pixel-scale.netlify.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/duniul.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,"publiccode":null,"codemeta":null}},"created_at":"2020-09-04T20:50:04.000Z","updated_at":"2024-12-27T01:59:15.000Z","dependencies_parsed_at":"2024-08-01T13:16:45.343Z","dependency_job_id":"0d6bb622-6238-4d44-b44e-dc752ef2be1c","html_url":"https://github.com/duniul/pixel-scale","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/duniul/pixel-scale","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duniul%2Fpixel-scale","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duniul%2Fpixel-scale/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duniul%2Fpixel-scale/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duniul%2Fpixel-scale/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/duniul","download_url":"https://codeload.github.com/duniul/pixel-scale/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/duniul%2Fpixel-scale/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266063102,"owners_count":23870719,"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":["canvas","image","image-processing","image-resize","imagedata","pixel-art","pixels"],"created_at":"2024-08-01T13:00:52.441Z","updated_at":"2025-07-20T03:31:20.281Z","avatar_url":"https://github.com/duniul.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://github.com/duniul/pixel-scale/blob/main/test/images/pixel-the-cat_x1.png\" /\u003e\n\u003cimg src=\"https://github.com/duniul/pixel-scale/blob/main/test/images/pixel-the-cat_x5.png\" /\u003e\n\u003cimg src=\"https://github.com/duniul/pixel-scale/blob/main/test/images/pixel-the-cat_x10.png\" /\u003e\n\u003c/p\u003e\n\n# pixel-scale\n\n[![](https://img.shields.io/npm/v/pixel-scale?color=brightgreen)](https://www.npmjs.com/package/pixel-scale)\n[![](https://img.shields.io/bundlephobia/minzip/pixel-scale)](https://bundlephobia.com/result?p=pixel-scale)\n\n📐 Get the pixel scale of an image, or scale it up or down without quality loss. Useful for pixel\nart!\n\n- 👀 Zero loss of quality\n- 🤖 Auto-detects current scale by default\n- ⏫ Can scale by multiplier or to a specific scale\n- 0️⃣ Zero dependencies\n- 🖼️ Works directly on [ImageData](#imagedata)\n\n\n## Table of contents\n\n- [Demo](#demo)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [`scalePixels(imageData, to, options)`](#scalepixelsimagedata-to-options)\n  - [`getPixelScale(imageData, options)`](#getpixelscaleimagedata-options)\n  - [`multiplyPixelScale(imageData, by, options)`](#multiplypixelscaleimagedata-by-options)\n  - [`dividePixelScale(imageData, by, options)`](#divideixelscaleimagedata-by-options)\n- [About](#about)\n  - [ImageData](#imagedata)\n  - [Pixel scale](#pixel-scale-1)\n  - [How does it work?](#how-does-it-work)\n\n## Demo\n\nhttps://pixel-scale.netlify.app\n\n## Installation\n\n| npm                       | yarn                    |\n| ------------------------- | ----------------------- |\n| `npm install pixel-scale` | `yarn add pixel-scale`  |\n\n## Usage\n\n### `scalePixels(imageData, to, options)`\n\nUp- or downscales an image to the specified scale, without losing quality or changing any colors.\n\n**Parameters:**\n\n- `imageData` (ImageData instance) - The ImageData instance to scale.\n\n- `to` (number) - The desired scale of the new image.\n\n- `options` (object, optional)\n  - `from` (number) - The current scale of the image. If no `from` value is provided, the scale is\n    calculated with `getPixelScale`. Only provide a `from` value if you are sure of the current\n    pixel scale and want to save time.\n  - `maxColorDiff` (number, default: 0) - Passed along to `getPixelScale` if no `from` value is set,\n    otherwise does nothing.\n\n**Return value:**\n\nA new, scaled ImageData-instance.\n\n**Examples:**\n\n```js\nimport { scalePixels } from 'pixel-scale';\n\n// detect an image's current scale, and rescale it to 1\nconst scale1ImageData = scalePixels(imageData, 1);\n\n// increase an image's scale from 5 to 10\nconst scale10ImageData = scalePixels(imageData, 10, { from: 5 });\n\n// detect an image's current scale, allowing a color diff of 10,\n// and rescale it to 2\nconst scale2ImageData = scalePixels(imageData, 2, { maxColorDiff: 10 });\n```\n\n### `getPixelScale(imageData, options)`\n\nGet the current pixel scale of an image.\n\n**Parameters:**\n\n- `imageData` (ImageData instance) - The ImageData instance to scale.\n\n- `options` (object, optional)\n\n  - `maxColorDiff` (number, default: 0) - See `scalePixels`'s `maxColorDiff` option.\n\n**Return value:**\n\nA number indicating the image's pixel scale.\n\n**Examples:**\n\n```js\nimport { getPixelScale } from 'pixel-scale';\n\n// get an image's pixel scale\nconst imageScale = getPixelScale(imageData);\n\n// get an image's pixel scale, allowing a maximum difference of 10 when comparing\n// color channels of individual pixels\nconst imageScale = getPixelScale(imageData, { maxColorDiff: 10 });\n```\n\n### `multiplyPixelScale(imageData, by, options)`\n\nSimilar to `scalePixels`, but upscales the image by the specified multiplier instead of to a specific scale. Detects the current scale of the image if no `options.from` value is provided.\n\n**Parameters:**\n\n- `imageData` (ImageData instance) - The ImageData instance to upscale.\n\n- `by` (number) - The amount to multiply the image's current scale by.\n\n- `options` (object, optional) - See `scalePixels`'s `options`.\n\n**Return value:**\n\nA new, scaled ImageData-instance.\n\n**Examples:**\n\n```js\nimport { multiplyPixelScale } from 'pixel-scale';\n\n// detect an image's current scale, and double it's size\nconst doubledImageData = multiplyPixelScale(imageData, 2);\n\n// take an image of scale 5, and multiply it by 10\nconst tenfoldImageData = multiplyPixelScale(imageData, 10, { from: 5 });\n```\n\n### `dividePixelScale(imageData, by, options)`\n\nSimilar to `scalePixels`, but downscales the image by the specified amount of times instead of to a specific scale. Detects the current scale of the image if no `options.from` value is provided.\n\n**Parameters:**\n\n- `imageData` (ImageData instance) - The ImageData instance to downscale.\n\n- `by` (number) - The amount to divide the image's current scale by.\n\n- `options` (object, optional) - See `scalePixels`'s `options`.\n\n**Return value:**\n\nA new, scaled ImageData-instance.\n\n**Examples:**\n\n```js\nimport { dividePixelScale } from 'pixel-scale';\n\n// detect an image's current scale, and make it half as big\nconst doubledImageData = dividePixelScale(imageData, 2);\n\n// take an image of scale 8 and divide it by 4\nconst tenfoldImageData = dividePixelScale(imageData, 4, { from: 8 });\n```\n\n## About\n\n### ImageData\n\nAll functions operate on [ImageData](https://developer.mozilla.org/en-US/docs/Web/API/ImageData),\nwhich can be retrieved from a\n[canvas](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas) in the browser or e.g.\n[node-canvas](https://github.com/Automattic/node-canvas) or [sharp](https://github.com/lovell/sharp)\non Node.\n\n### Pixel scale\n\nThe pixel scale referred to in this readme is the amount of times a pixel of e.g. a pixel art image\nhas been multiplied to increase the image size. For example,\n[this image](https://github.com/duniul/pixel-scale/blob/master/test/images/pixel-the-cat_x1.png) has\na pixel scale of 1, while\n[this image](https://github.com/duniul/pixel-scale/blob/master/test/images/pixel-the-cat_x10.png)\nhas a pixel scale of 10.\n\n### How does it work?\n\nTo get the pixel scale of an image, `pixel-scale` first figures out the common divisors of the\nimage's height and width. This is done using Euclid's algorithm for finding the greatest common\ndivisor, and then counting down. A more performant method (e.g. prime factorization/Pollard rho) is\nnot deemed necessary here, as image dimensions never go up to those sizes that big.\n\nIt then tests each common divisor, starting with the largest one, by chunking up the image equally\nsized pieces and verifying that they each chunk is in a solid color (scaled pixels). If a chunk\ncontains a different color outside of the max allowed span (`maxColorDiff`), then it will go to the\nnext divisor. If every chunk is a solid color, then the divisor is most likely the pixel scale of\nthe image.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduniul%2Fpixel-scale","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fduniul%2Fpixel-scale","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fduniul%2Fpixel-scale/lists"}