{"id":21917480,"url":"https://github.com/clusterm/nestiler","last_synced_at":"2025-07-26T07:03:42.961Z","repository":{"id":48971074,"uuid":"306079523","full_name":"ClusterM/NesTiler","owner":"ClusterM","description":"Tool for converting images into NES format: generating pattern tables, palettes, name tables","archived":false,"fork":false,"pushed_at":"2024-08-31T10:55:30.000Z","size":1441,"stargazers_count":37,"open_issues_count":1,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-19T05:36:01.211Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ClusterM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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,"zenodo":null},"funding":{"github":["ClusterM"],"custom":["https://www.buymeacoffee.com/cluster","https://boosty.to/cluster"]}},"created_at":"2020-10-21T16:09:57.000Z","updated_at":"2025-05-09T23:35:00.000Z","dependencies_parsed_at":"2024-02-20T19:54:47.660Z","dependency_job_id":"bdd8619a-e970-4d60-ae30-172043f5ff36","html_url":"https://github.com/ClusterM/NesTiler","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ClusterM/NesTiler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClusterM%2FNesTiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClusterM%2FNesTiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClusterM%2FNesTiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClusterM%2FNesTiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClusterM","download_url":"https://codeload.github.com/ClusterM/NesTiler/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClusterM%2FNesTiler/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267133548,"owners_count":24040780,"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","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-28T19:32:47.735Z","updated_at":"2025-07-26T07:03:42.888Z","avatar_url":"https://github.com/ClusterM.png","language":"C#","funding_links":["https://github.com/sponsors/ClusterM","https://www.buymeacoffee.com/cluster","https://boosty.to/cluster"],"categories":[],"sub_categories":[],"readme":"# NesTiler\r\n[![Build, test, upload](https://github.com/ClusterM/NesTiler/actions/workflows/build-test.yml/badge.svg)](https://github.com/ClusterM/NesTiler/actions/workflows/build-test.yml)\r\n\r\nTool for converting pictures into NES format: pattern tables, nametables, attribute tables and palettes.\r\n\r\n## What does it do\r\nWhen developing applications and games for NES you have to perform a lot of routine. To display images you need to split each image into tiles, combine tiles into nametables, select colors so that they do not go beyond the limits of the NES, and then convert all this into a format understandable for NES. This tool at least partially helps to automate this process. \r\n\r\nThis application can accept multiple images as input, the main point is to use single set of palettes (and tiles if required) for all of them, so it's possible to switch CHR banks and base nametable on a certain line, in the middle of rendering process. You can't change palettes while image renders, so palette set must be the same for all images. \r\n\r\nOf course, the ideal result will be achieved only in the case of properly prepared images that do not go beyond the limitations of NES. But it's possible to do lossy conversion too. \r\n\r\nCheck [Examples](https://github.com/ClusterM/NesTiler/tree/master/Examples) directory for examples.\r\n\r\nThe sequence of actions is as follows:\r\n* Load available NES colors from JSON or PAL file and their indices.\r\n\r\n![NES colors](https://user-images.githubusercontent.com/4236181/198836117-35c87207-0f39-40cd-90f0-b38a24c648f7.png)\r\n\r\n* Load images, crop/split them if need\r\n\r\n![Loading images](https://user-images.githubusercontent.com/4236181/198837161-6e514f3b-9512-4501-8f44-846b20b6ea3c.png)\r\n\r\n* Change every pixel of each image, so it's matches most similar color from available NES colors\r\n\r\n![Recolor image](https://user-images.githubusercontent.com/4236181/198837207-8e45433a-60eb-4c80-9b6b-1dd8a12e285b.png)\r\n\r\n* Calculate desired number of palettes to fit every image or at least trying to do it\r\n\r\n![Palettes](https://user-images.githubusercontent.com/4236181/198837449-35a6c26c-5bd7-4aa3-8076-2ca498e0c1aa.png)\r\n\r\n* Generate attribute table for each image, assign palette index for each tiles set\r\n\r\n![Attribute tables](https://user-images.githubusercontent.com/4236181/198837666-b67b1a82-1b18-4fee-b33c-fa833df18b63.png)\r\n\r\n* Change colors of every tile to match assigned palette index (if need)\r\n\r\n![Recolor tiles](https://user-images.githubusercontent.com/4236181/198837858-e38bc6af-1d18-46c5-83fc-c8348dbc130f.png)\r\n\r\n* Create set of tiles, trying to fit them into 256, grouping same tiles into one\r\n\r\n![Tiles](https://user-images.githubusercontent.com/4236181/198838408-660c252e-ec75-408b-9fbd-36d7a77f97b0.png)\r\n\r\n* Save pattern table and nametable of each image to file, so it's easy to include them to NES ROM and show the image (NES has non-square pixels, so image is stretched)\r\n\r\n![Result](https://user-images.githubusercontent.com/4236181/198838556-1ff947ba-9879-49f1-a74d-3b8df7067051.png)\r\n\r\n## How to use\r\n\r\n```\r\nUsage: nestiler.exe \u003coptions\u003e\r\n\r\nAvailable options:\r\n-i\u003c#\u003e --in-\u003c#\u003e \u003cfilename\u003e[:offset[:height]]     input filename number #, optionally cropped vertically\r\n-c    --colors \u003cfilename\u003e                       JSON or PAL file with the list of available colors\r\n                                                (default - nestiler-colors.json)\r\n-m    --mode bg|sprites8x8|sprites8x16          mode: backgrounds, 8x8 sprites or 8x16 sprites (default - bg)\r\n-b    --bg-color \u003ccolor\u003e                        background color in HTML color format (default - auto)\r\n-e    --enable-palettes \u003cpalettes\u003e              zero-based comma separated list of palette numbers to use\r\n                                                (default - 0,1,2,3)\r\n-p\u003c#\u003e --palette-\u003c#\u003e \u003ccolors\u003e                    comma separated list of colors to use in palette number #\r\n                                                (default - auto)\r\n-o\u003c#\u003e --pattern-offset-\u003c#\u003e \u003ctile_index\u003e         first tile index for pattern table for file number # (default - 0)\r\n-y\u003c#\u003e --attribute-table-y-offset-\u003c#\u003e \u003cpixels\u003e   vertical offset for attribute table in pixels (default - 0)\r\n-s    --share-pattern-table                     share pattern table between input images\r\n-r\u003c#\u003e --no-group-tiles-\u003c#\u003e                      do not group similar tiles in pattern table\r\n-l    --lossy \u003clevel\u003e                           lossy level: 0-3, defines how many color distortion is allowed\r\n                                                without throwing an error (default - 2)\r\n-v\u003c#\u003e --out-preview-\u003c#\u003e \u003cfilename.png\u003e          output filename for preview of image number #\r\n-t\u003c#\u003e --out-palette-\u003c#\u003e \u003cfilename\u003e              output filename for palette number #\r\n-n\u003c#\u003e --out-pattern-table-\u003c#\u003e \u003cfilename\u003e        output filename for pattern table of image number #\r\n-a\u003c#\u003e --out-name-table-\u003c#\u003e \u003cfilename\u003e           output filename for nametable of image number #\r\n-u\u003c#\u003e --out-attribute-table-\u003c#\u003e \u003cfilename\u003e      output filename for attribute table of image number #\r\n-z    --out-tiles-csv \u003cfilename.csv\u003e            output filename for tiles info in CSV format\r\n-x    --out-palettes-csv \u003cfilename.csv\u003e         output filename for palettes info in CSV format\r\n-g    --out-colors-table \u003cfilename.png\u003e         output filename for graphical table of available colors\r\n                                                (from \"--colors\" option)\r\n-q    --quiet                                   suppress console output\r\n```\r\n\r\n### Option -i\u003c#\u003e, --in-\u003c#\u003e \\\u003cfile\\\u003e[:offset[:height]]\r\nOption to specify input images filenames. You need to replace __#__ with image index (any number), so you can specify multiple images. Index will be used to identify output filenames.\r\n\r\nExamples:\r\n* `nestiler -i0 image1.png -i1 image2.png -i2 image3.png ...`\r\n* `nestiler --in-0 image1.png --in-1 image2.png --in-2 image3.png ...`\r\n \r\nAlso, you can load image partially - split them horizontally, just add offset and height after colon. So if you need to split 256x240 image into two images:\r\n* nestiler -i0 image.png:0:128 -i1 image.png:128:112\r\n\r\nIt's useful if you need to show single image on screen but you want to split it into two 256-tiles pattern tables and switch them on specific line in the middle of rendering process.\r\n\r\n### Option -c, --colors \\\u003cfile\\\u003e\r\nOption to specify file with available colors and indices. This file can be in JSON format (see nestiler-colors.json) or binary PAL format (used by emulators).\r\n\r\nExamples:\r\n* `nestiler -c nestiler-colors.json ...`\r\n* `nestiler --colors nestiler-colors.json ...`\r\n\r\nPlease note that some colors have caveats surrounding their usage on NES. 0x0D (\"blacker than black\") is forbidden and will be ignored.\r\nAlso be aware that 0x1D (black) is affected by emphasis bits when other black colors 0xXE-0xXF are not.\r\n\r\n### Option -m, --mode bg|sprites8x8|sprites8x16\r\nOption to specify processing mode: backgrounds, 8x8 sprites or 8x16 sprites. Default is backgrounds mode.\r\n\r\nExamples:\r\n* `nestiler -m bg ...`\r\n* `nestiler --mode sprites8x8 ...`\r\n\r\n### Option -b, --bg-color \\\u003ccolor\\\u003e\r\nBackground color in HTML format. Optional for background mode (will be set automatically) and required for sprite modes.\r\n\r\nExamples:\r\n* `nestiler -b #C4C4C4 ...`\r\n* `nestiler --bg-color #000000 ...`\r\n\r\n### Option -e, --enable-palettes \\\u003cpalettes\\\u003e\r\nList of palette numbers (4-color combinations) to use, zero-based, comma separated: from 0 to 3. Useful when you need to fit image into limited amount of palettes (when lossy level = 3) or get error if you can't fit in them (when lossy level \u003c 2, see below). Default value is all - 0,1,2,3.\r\n\r\nExamples:\r\n* `nestiler -e 0,1,2,3 ...`\r\n* `nestiler --enable-palettes 0,1 ...`\r\n\r\n### Option -p\u003c#\u003e, --palette-\u003c#\u003e \\\u003ccolors\\\u003e\r\nComma separated list of colors to use in palette number __#__ (0-3). Using this option you can manually specify palettes to use (three color sets), HTML format, comma separated. Three colors instead of four because background color shared between all palettes. Useful if you need fixed palette for other purposes, it can be shared with your image.\r\n\r\nExamples:\r\n* `nestiler -p0 #747474,#A40000,#004400 -p2 #8000F0,#D82800,#FCFCFC ...`\r\n* `nestiler --palette-0 #5C94FC,#FC7460,#FC9838 --palette-1 #80D010,#58F898,#787878 ...`\r\n\r\nPlease note that index here is palette number, not input file number.\r\n\r\n### Option -o\u003c#\u003e, --pattern-offset-\u003c#\u003e \\\u003ctile_id\\\u003e\r\nUsing this option you can set first tile index to use with image number __#__. Useful if you need to reserve some space in the begining of pattern table. Default valus is 0.\r\n\r\nExamples:\r\n* `nestiler -o1 32 ...`\r\n* `nestiler --pattern-offset-5 100 ...`\r\n\r\n__#__ number is ignored when the \"__--share-pattern-table__\" option is used (see below), you can write just \"__--pattern-offset__\".\r\n\r\n### Option -y\u003c#\u003e, --attribute-table-y-offset-\u003c#\u003e \\\u003cpixels\\\u003e\r\nOne attribute table byte stores four palette indices for 16 tiles (4x4 square). It can cause problems if your image should be displayed on lines whose numbers are not divisible by 32. Using this option you can set vertical image offset for image number __#__ - amount of pixels divisible by 8. Default value is 0. Please note that you need to care about unused bits manually.\r\n\r\nExamples:\r\n* `nestiler -y1 32 ...`\r\n* `nestiler --attribute-table-y-offset-0 16 ...`\r\n\r\n### Option -s, --share-pattern-table\r\nUse this option if you need to share single pattern table between all input images. Useful if you need to scroll screen horizontally.\r\n\r\nExamples:\r\n* `nestiler -s ...`\r\n* `nestiler --share-pattern-table ...`\r\n\r\n### Option -r, --no-group-tiles-\u003c#\u003e\r\nBy default, NesTiles groups the same tiles into one. You can use this option to disable this behavior. It's useful, especially when you need to keep the order of tiles. This is particularly important for tiles with characters such as letters or digits, for example.\r\n\r\nExamples:\r\n* `nestiler -r1 ...`\r\n* `nestiler --no-group-tiles-0 ...`\r\n\r\n### Option -l, --lossy \\\u003clevel\\\u003e\r\nLossy level: 0-3, defines how many color distortion is allowed without throwing an error.\r\n\r\n* 0 - throw error even if any pixel of any input image is not from NES colors (from file specified by __--colors__ option)\r\n* 1 - ignore errors from level 0 by replacing every pixel color with most similar NES color, but throw error if any input image contains tile with more than four colors\r\n* 2 - ignore errors from levels 0 and 1 by replacing unwanted colors with most similar available, but throw error if there are more than 4 (or less if __--enable-palettes__ option is used)\r\n* 3 - ignore all color ploblems by replacing unwanted colors with most similar available\r\n  \r\nDefault value is 2.\r\n\r\nExamples:\r\n* `nestiler -l 0 ...`\r\n* `nestiler --lossy 3 ...`\r\n  \r\n### Option -v\u003c#\u003e, --out-preview-\u003c#\u003e \\\u003cfile.png\\\u003e\r\nOption to save preview for input image number __#__. Stored as PNG file. Useful if you need to preview result without compiling ROM. Preview is not saved if option is not specified.\r\n\r\nExamples:\r\n* `nestiler -v0 preview.png -v1 preview2.png ...`\r\n* `nestiler --out-preview-1 image.png --out-preview-2 image2.png ...`\r\n\r\n### Option -t\u003c#\u003e, --out-palette-\u003c#\u003e \\\u003cfilename\\\u003e\r\nOption to save generated palette number __#__. Just four bytes with color indices. Not saved if option is not specified.\r\n\r\nExamples:\r\n* `nestiler -t0 palette0.bin -t0 palette2.bin ...`\r\n* `nestiler --out-palette-1 palette1.bin --out-palette-2 palette2.bin ...`\r\n\r\nPlease note that index here is palette number, not input file number.\r\n\r\n### Option -n\u003c#\u003e, --out-pattern-table-\u003c#\u003e \\\u003cfilename\\\u003e\r\nOption to save generated pattern table for image number __#__. 16 bytes per tile, 960 bytes per full screen image. Not saved if option is not specified.\r\n\r\n__#__ number is ignored when the \"__--share-pattern-table__\" option is used (see below), you can write just \"__--out-pattern-table__\".\r\n\r\nExamples:\r\n* `nestiler -n0 pattern0.bin -n1 pattern1.bin ...`\r\n* `nestiler --out-pattern-table-2 out.bin --out-pattern-table-3 out2.bin ...`\r\n\r\n### Option -a\u003c#\u003e, --out-name-table-\u003c#\u003e \\\u003cfilename\\\u003e           \r\nOption to save generated nametable for image number __#__. 16 bytes per tile, 960 bytes per full screen image. Not saved if option is not specified.\r\n\r\nExamples:\r\n* `nestiler -a2 nt2.bin -a3 nt3.bin ...`\r\n* `nestiler --out-name-table-1 nametable.bin --out-name-table-2 nametable2.bin ...`\r\n\r\n### Option -u\u003c#\u003e, --out-attribute-table-\u003c#\u003e \\\u003cfilename\\\u003e\r\nOption to save generated attribute table for image number __#__. 1 byte per 16 tiles. 64 bytes per full screen image. Not saved if option is not specified. Can't be used in sprite modes.\r\n\r\nExamples:\r\n* `nestiler -u0 attr_a.bin -u1 attr_b.bin ...`\r\n* `nestiler --out-attribute-table-1 attrtable1.bin --out-attribute-table-2 attrtable2.bin ...`\r\n\r\n### Option -z, --out-tiles-csv \\\u003cfilename.csv\\\u003e\r\nOption to save CSV file with tiles information for all input images: indices, used palettes, etc. Not saved if option is not specified.\r\n\r\nExamples:\r\n* `nestiler -z tiles.csv ...`\r\n* `nestiler --out-tiles-csv tiles.csv ...`\r\n\r\n### Option -x, --out-palettes-csv \\\u003cfilename.csv\\\u003e\r\nOption to save CSV file with palettes data: indices and colors.\r\n\r\nExamples:\r\n* `nestiler -x palettes.csv ...`\r\n* `nestiler --out-palettes-csv palettes.csv ...`\r\n\r\n### Option -g, --out-colors-table \\\u003cfilename.png\\\u003e\r\nOption to generate PNG file with table of available NES colors (from __--colors__ option). Useful for reference when drawing. This option can be used without any input images.\r\n\r\nExamples:\r\n* `nestiler -g colors.png`\r\n* `nestiler --out-colors-table colors.png`\r\n\r\n### Option -q, --quiet\r\nJust option to suppress console output.\r\n\r\nExamples:\r\n* `nestiler -q`\r\n* `nestiler -quiet ...`\r\n\r\n## Download\r\nYou can always download latest version at [https://github.com/ClusterM/NesTiler/releases](https://github.com/ClusterM/NesTiler/releases).\r\n\r\nAlso, you can download automatic interim builds: [http://clusterm.github.io/NesTiler/](http://clusterm.github.io/NesTiler/).\r\n\r\n## Donate\r\n* [Buy Me A Coffee](https://www.buymeacoffee.com/cluster)\r\n* [Donation Alerts](https://www.donationalerts.com/r/clustermeerkat)\r\n* [Boosty](https://boosty.to/cluster)\r\n* BTC: 1MBYsGczwCypXhMBocoDQWxx7KZT2iiwzJ\r\n* PayPal is not available in Armenia :(\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclusterm%2Fnestiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclusterm%2Fnestiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclusterm%2Fnestiler/lists"}