{"id":28418824,"url":"https://github.com/mjurczyk/png-to-hex","last_synced_at":"2025-07-16T18:06:54.549Z","repository":{"id":31781586,"uuid":"35347982","full_name":"mjurczyk/png-to-hex","owner":"mjurczyk","description":"Easily convert PNG images into hexadecimal value batches.","archived":false,"fork":false,"pushed_at":"2015-05-10T16:00:21.000Z","size":212,"stargazers_count":10,"open_issues_count":0,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-05T17:02:34.128Z","etag":null,"topics":["binary-converter","digital-image-processing","png"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mjurczyk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-09T22:33:15.000Z","updated_at":"2025-05-28T05:19:48.000Z","dependencies_parsed_at":"2022-09-21T01:51:34.275Z","dependency_job_id":null,"html_url":"https://github.com/mjurczyk/png-to-hex","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mjurczyk/png-to-hex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjurczyk%2Fpng-to-hex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjurczyk%2Fpng-to-hex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjurczyk%2Fpng-to-hex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjurczyk%2Fpng-to-hex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mjurczyk","download_url":"https://codeload.github.com/mjurczyk/png-to-hex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mjurczyk%2Fpng-to-hex/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265529093,"owners_count":23782822,"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":["binary-converter","digital-image-processing","png"],"created_at":"2025-06-04T12:48:00.579Z","updated_at":"2025-07-16T18:06:54.543Z","avatar_url":"https://github.com/mjurczyk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n![header](http://mjurczyk.github.io/png-to-hex/pikachu-header.png)\n# PNG-to-HEX\n\u003e Easily convert PNG images into hexadecimal value batches.\n\n## What\nThis module might be a Google Plus of npm modules, however for some it might be extremely helpful during small hardware projects, display testing etc.\nWhile working with bare, low level hardware we sometimes want or need to display a complex pixel structure, like a font or image. If you wish to store either of these in your codebase (for example a default system font), it might be tiresome to prepare a hex table for it. This library generates the hex table for you, and presents it in a C-style code, ready for use in your project.\n\n## How it works\n![example](http://mjurczyk.github.io/png-to-hex/pikachu-transform-example.png)\n\nAt first, module grabs your image and desaturates it. After that, the black\u0026white image is split into a table of batches (or stripes).\nEach batch is then carefully transformed into binary numbers, and then once more, into hexadecimal values.\nIn the end, the final array of hex values is injected into `static const` C variable definition, along with the number of rows and size of each batch.\nFrom that moment you are ready to copy the result, pop it into your code and use in the project.\n\n## How to use it (Stand-alone | Grunt task)\n\n### Prepare image\nIn order to convert an image, you have to make sure it can be divided into batches. By default, batch size is 5x8\u003csup\u003e1\u003c/sup\u003e. Hance, your image width has to be divisible by 5, and its height has to be divisible by 8 (ex. 45x48). Otherwise, converter may not want to cooperate.\n\n\u003csup\u003e1\u003c/sup\u003e You can configure the batch size with `batchWidth` and `batchHeight` parameters\n\n### Install module\n1. First of all, you will need `nodejs` installed on your computer. You can grab the latest version [here](https://nodejs.org/download/). This will install both `node` and `npm` for you.\n2. Since you already have `npm`, you can now go to a desired directory, open terminal there and type `npm init`. This will create a npm project in the directory and allow us to install additional modules. Feel free to quickly click-through all prompts, they do not matter in our case.\n2. With set up project, type `npm install png-to-hex`. It will download and install the png-to-hex package.\n\n### Stand-alone command\n*(For the sake of example, I'll assume we do everything in the module directory)*\n1. In the directory create a `assets` folder and put your 45x48 image inside.\n2. In the directory create configuration file `config.json`. Inside of it write:\n```json\n{\n  \"input\": \"./assets/image.png\",\n  \"output\": \"image\",\n  \"outputDir\": \"./output\",\n  \n  \"minify\": false,\n  \n  \"preview\": true,\n  \"previewDir\": \"./preview\"\n}\n```\n3. Now open the terminal console in the directory and type `node node_modules/png-to-hex -c config.json`. \n4. Your output files have been generated and put in `output` directory, a preview of the converted image has been placed in `preview` folder.\n\n### Grunt command\u003csup\u003e2\u003c/sup\u003e\n*(For the sake of example, I'll assume we do everything in the module directory)*\n\nThe module is also available as a Grunt command, which can really speed up the process of converting due to Grunt's file system nature.\n\n1. In the directory create a `assets` folder and put your 45x48 image(s) inside.\n2. In the directory create a `Gruntfile.js`:\n```js\nmodule.exports = function (grunt) {\n  grunt.initConfig({\n    png2hex: {\n      options: {\n        // Don't minify the output\n        minify: false,\n        \n        // Generate preview files\n        preview: true\n      },\n      convert: {\n        src: ['./assets/**/*.png']\n      }\n    }\n  });\n  \n  grunt.loadNpmTasks('png-to-hex');\n  \n  grunt.registerTask('default', ['png2hex']);\n};\n```\n3. Now open the terminal console in the directory and type `grunt`.\n4. Your output files have been generated and put in `output` directory, a preview of the converted image has been placed in `preview` folder.\n\n\u003csup\u003e2\u003c/sup\u003e If you have never used Grunt before, make sure to check [this](http://gruntjs.com/getting-started) out, or just use the stand-alone version of the module.\n\n## Configuration\n\nPng-to-hex due to its purpose is quite enclosed, but still provides a bunch of configurable options you might want to use one day.\n\n### How to configure PNG-to-HEX\nThere are total of 3 ways to tell the module what you want to be done. You can either use `config.json` file and pass it via command to the module. You can write configuration in the `Gruntfile.js` task options. Or you can simply write options in the command line, ex:\n```bash\nnode node_modules/png-to-hex -input ./myfile.png -output converted_file -minify -preview -thr 1.5\n```\nEither way you choose, the effect will be similar. Below you will find the reference notes regarding all possible options.\n\n### Reference\n\n#### config\n\u003e Path to the configuration file. If defined, configuration read from the file will override all other settings.\n\ncli: ***-c*** | ***-conf*** | ***-config***\n\ndefault: ***undefined***\n\n#### input\n\u003e Input file(s).\n\ncli: ***-i*** | ***-input*** | ***-f*** | ***-file*** | (last argument passed in cli)\n\ndefault: ***undefined***\n\nrequired: ***true***\n\n#### output\n\u003e Output name (for both file and hex table variable). This has to be a valid C variable name (module will notify you, if it is not ok).\n\ncli: ***-o*** | ***-output***\n\ndefault: ***'image'***\n\n#### outputDir\n\u003e Output directory.\n\ncli: ***-odir***\n\ndefault: ***'./output'***\n\n#### outputExt\n\u003e Output file extension.\n\ncli: ***-oext***\n\ndefault: ***'txt'***\n\n#### minify\n\u003e If set to true, converter will remove all unnecessary whitespace from the output and present it as a single-line hex table.\n\ncli: ***-min*** | ***-minify***\n\ndefault: ***false***\n\n#### pngFilter\n\u003e [node-png](https://github.com/liangzeng/node-png) filtering value.\n\ncli: ***-flt*** | ***-filter***\n\ndefault: ***-1***\n\n#### bwThreshold\n\u003e Black/white threshold. Converted sums RGB channels for each pixel, and depending on the bwThreshold value, sets the pixel to either black (1) or white (0).\n\ncli: ***-thr*** | ***-threshold***\n\ndefault: ***1.7***\n\n#### batchWidth\n\u003e Batch size. Image width has to be divisible by batchWidth.\n\u003e If set to imageWidth, converter will produce stripes instead of batches.\n\ncli: ***-w*** | ***-width***\n\ndefault: ***5***\n\n#### batchHeight\n\u003e Batch size. Batch height usually depends on the application. For 8-bit displays you want to keep it 8. If you display write buffer is 16, 32 etc. you ought to adjust the height.\n\ncli: ***-h*** | ***-height***\n\ndefault: ***8***\n\n#### preview\n\u003e If set to true, transformed images will be saved in the preview directory (useful when you try different bwThreshold values on your images).\n\ncli: ***-p*** | ***-preview***\n\ndefault: ***false***\n\n#### previewDir\n\u003e Preview files directory.\n\ncli: ***-pdir***\n\ndefault: ***'./preview'***\n\n#### previewExt\n\u003e Preview files extension. This does not affect the true extension of the file, which will still be a png.\n\ncli: ***-pext***\n\ndefault: ***'png'***\n\n## Sample implementation\nThis is a sample implementation of the final hex table on Nokia 5110 display:\n\n```C\n/*\n * Png-to-hex output\n */\nstatic const unsigned int image_width = 4;\nstatic const unsigned int image_height = 4;\nstatic const byte image[][4] = {{ ... }};\n\n/*\n * Write data to the display.\n * @param  dc    data/!command switch\n * @param  data  output value\n */\nvoid dWrite (byte dc, byte data) {\n  digitalWrite(PIN_DC, dc);\n  \n  digitalWrite(PIN_SCE, LOW);\n  shiftOut(PIN_SDIN, PIN_SCLK, MSBFIRST, data);\n  digitalWrite(PIN_SCE, HIGH); \n}\n\n/*\n * Set cursor position on display.\n * @param  x  horizontal position\n * @param  y  vertical position\n */\nvoid dPos (unsigned int x, unsigned int y) {\n  dWrite(0, 0x80 | x);\n  dWrite(0, 0x40 | y);\n}\n\n/*\n * Draw image on display.\n * @param  image  hex table\n * @param  width  # vertical segments\n * @param  height # horizontal segments\n */\nvoid dDraw (const byte image[][4], int width, int height) {\n  int y;\n  int x;\n  int col;\n  \n  for (y = 0; y \u003c height; y++) {\n    dPos(0, y);\n    for (x = 0; x \u003c width; x++) {\n      for (col = 0; col \u003c 4; col++) {\n        dWrite(LCD_D, image[x + y * width][col]);\n      }\n    }\n  }\n}\n\n/* ... */\n\ndDraw(image, image_width, image_height);\n```\n\n## Licence\n\nMIT :octocat:\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjurczyk%2Fpng-to-hex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmjurczyk%2Fpng-to-hex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmjurczyk%2Fpng-to-hex/lists"}