├── .gitattributes ├── LICENSE ├── README.md ├── examples ├── animation.bimg └── image.bimg ├── images ├── file-structure.png └── frame-structure.png ├── rough-ideas.md └── spec.md /.gitattributes: -------------------------------------------------------------------------------- 1 | *.bing linguist-language=lua 2 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 SkyTheCodeMaster 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # bimg 2 | Universal image format for ComputerCraft 3 | 4 | # Jamboard for ideas 5 | https://jamboard.google.com/d/1kPiEZHSiuq6dkofe2g8DpsBH6DTV1JkMXfzt24mhDdY/edit?usp=sharing 6 | -------------------------------------------------------------------------------- /examples/animation.bimg: -------------------------------------------------------------------------------- 1 | -- Example bimg animation file with every metadata field filled out. 2 | { 3 | { 4 | { 5 | "First Line", 6 | "0000000000", 7 | "ffffffffff", 8 | }, 9 | { 10 | "Bimg Image", 11 | "dddd0aaaaa", 12 | "ffffffffff", 13 | }, 14 | }, 15 | { 16 | { 17 | "First Line", 18 | "8888888888", 19 | "ffffffffff", 20 | }, 21 | { 22 | "Bimg Image", 23 | "22220aaaaa", 24 | "ffffffffff", 25 | }, 26 | }, 27 | { 28 | duration = 0.6, -- Make this frame last 3x longer (0.6 seconds vs default 0.2 seconds) 29 | { 30 | "First Line", 31 | "7777777777", 32 | "ffffffffff", 33 | }, 34 | { 35 | "Bimg Image", 36 | "66660aaaaa", 37 | "ffffffffff", 38 | }, 39 | }, 40 | version = "1.0.0", 41 | animation = true, -- Important for animations! 42 | secondsPerFrame = 0.2, -- 0.2 seconds per frame (5FPS) as the default delay between drawing each frame. 43 | palette = { -- Only defining the colours required, but can define all if needed. 44 | [colors.white] = { 0xffffff }, 45 | [colors.purple] = { 0xb266e5 }, 46 | [colors.green] = { 0x57a64e }, 47 | [colors.black] = { 0x000000 }, -- Only defining a default palette 48 | }, 49 | title = "Example Animation", 50 | description = "This is an example of the .bimg animation format, a universal ComputerCraft image.", 51 | author = "SkyTheCodeMaster", 52 | creator = "Keyboard and Mouse", 53 | date = "2022-05-31T03:09:27+0000", 54 | } 55 | -------------------------------------------------------------------------------- /examples/image.bimg: -------------------------------------------------------------------------------- 1 | -- Example bimg file with every metadata field filled out. 2 | { 3 | { 4 | { 5 | "First Line", 6 | "0000000000", 7 | "ffffffffff", 8 | }, 9 | { 10 | "Bimg Image", 11 | "dddd0aaaaa", 12 | "ffffffffff", 13 | }, 14 | }, 15 | version = "1.0.0", 16 | animation = false, 17 | palette = { -- Only defining the colours required, but can define all if needed. 18 | [colors.white] = { 0xffffff }, 19 | [colors.purple] = { 0xb266e5 }, 20 | [colors.green] = { 0x57a64e }, 21 | [colors.black] = { 0x000000 }, 22 | }, 23 | title = "Example", 24 | description = "This is an example of the .bimg format, a universal ComputerCraft image.", 25 | author = "SkyTheCodeMaster", 26 | creator = "Keyboard and Mouse", 27 | date = "2022-05-30T22:32:24+0000", 28 | } 29 | -------------------------------------------------------------------------------- /images/file-structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SkyTheCodeMaster/bimg/bfc212dacff1e184bd8357d5b6f51a1b886ed85d/images/file-structure.png -------------------------------------------------------------------------------- /images/frame-structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SkyTheCodeMaster/bimg/bfc212dacff1e184bd8357d5b6f51a1b886ed85d/images/frame-structure.png -------------------------------------------------------------------------------- /rough-ideas.md: -------------------------------------------------------------------------------- 1 | # Rough Ideas 2 | These are a rough set of fields in the `.bimg` format. 3 | 4 | # Image data 5 | A line is a tuple of (text, text colors, background colors) in blit format. 6 | Frames are lists of lines. 7 | Image files may be a single frame, or list of frames. 8 | Each frame can have a `palette` key to specify a specific palette for that frame, following the rules of the base `palette` key. 9 | 10 | # Metadata 11 | Metadata is stored at the root of the table. 12 | `version`: string Version string of the format. 13 | `animation`: boolean Whether the image is an animation (if so, each frame is numerically indexed). 14 | (per frame) `duration`: number Duration of the frame in seconds, overrides `secondsPerFrame` for that frame. 15 | `secondsPerFrame`: number Default length of each frame in seconds. 16 | `palette`: table Palette table in format of colors api (key: color number - value: EITHER table of 3 ranged 0-1 floats for each RGB component, OR a single item which is the hex-formatted number #RRGGBB). This will serve as the starting palette for any animations or images. 17 | (per frame) `palette`: table Per frame palette, set before drawing the frame. Same format as the root `palette`. 18 | 19 | `title`: string Original title of the image. 20 | `description`: Long form description of the file. 21 | `author`: Author of the image. 22 | `creator`: Software used to create the image. 23 | `date`: Date the image was created in ISO-8601 format. 24 | -------------------------------------------------------------------------------- /spec.md: -------------------------------------------------------------------------------- 1 | # bimg File Format Specification 2 | Version 1.0.0 (2022-07-29) 3 | 4 | bimg (abbreviation of "blit image") is a versatile image format for the ComputerCraft Minecraft mod. 5 | This specification aims to provide a standardized image format that can be easily implemented and used throughout the entire ComputerCraft ecosystem. 6 | 7 | # File Structure 8 | The examples shown throughout this specification are based on a sample image file, serialized using `textutils.serialize`. 9 | 10 | An image file can be separated into two sections: metadata and frame data. These two sections are unordered, meaning that they can be correctly written and read by parsers regardless of whether the metadata or the frame data comes first: 11 | ![Format overview](images/file-structure.png?raw=true) 12 | 13 | Metadata contains information about the image itself, while the remaining of the file contains one or more frames, representing the images. 14 | 15 | For more information on metadata, see [Metadata](#metadata). For more information on the image data and frames, see [Image Data](#image-data) 16 | . 17 | # Metadata 18 | bimg stores the following metadata along the image data in the file. 19 | 20 | | Field | Type | Description | 21 | |:--|:-:|:--| 22 | | `version` | `string` | Format version of the file. Used to differentiate two bimg file formats. Composed of three numbers separated by dots, defining the major, minor, and revision number respectively. | 23 | | `author` | `string` | Author of the image. | 24 | | `title` | `string` | Title of the image. Set by the author. 25 | | `description` | `string` | Description of the image. Set by the author. | 26 | | `creator` | `string` | Software that created the image. | 27 | | `date` | `string` | Date and time the image was created on, in ISO-8601 format. | 28 | | `width` | `number` | Width of the image in characters. | 29 | | `height` | `number` | Height of the image in characters. | 30 | | `animated` | `boolean` | Whether the file contains multiple frames and can be interpreted as an [animation](#animations). 31 | | (if animated) `secondsPerFrame` | `number` | Default length of each frame in seconds. 32 | | `palette` | `table` | Color palette table applied to the whole set of frames. For more information on palette formats, see [Palettes](#palettes). 33 | 34 | All metadata fields are optional, besides the `version` and `animated` fields. When the `animated` field is set to `true`, the `secondsPerFrame` is expected, but not required. 35 | 36 | # Image Data 37 | Aside the metadata are stored the frames of the image. At least one frame must be present for the file to be considered valid. 38 | For animation support, see [Animations](#animations). 39 | 40 | ## Frame Structure 41 | A single frame is composed of multiple numerically-indexed tables, each representing a single line of the image. 42 | Additionally, an optional per-frame palette can be provided to alter the colors of that frame only. For more information on palettes, see [Palettes](#palettes). 43 | 44 | When the image is an animation, an optional `duration` field can also be provided. This field overrides the `secondsPerFrame` field set in the metadata, and therefore sets a specific duration (in seconds) for that frame only. 45 | 46 | ![Frame Data](images/frame-structure.png) 47 | 48 | Each line is composed of three `string` values forming a blit table, that can be unpacked directly to `term.blit` when rendering the image. 49 | 50 | Spaces in any of the blit strings should make the corresponding color of the pixel transparent, according to the following rules: 51 | | Foreground | Background | Result | 52 | |:-:|:-:|---| 53 | | Colored | Colored | The pixel is rendered as is, using the colors set in the blit strings. No transparency is applied. | 54 | | Colored | Transparent | The background color of the pixel that is about to be replaced is used as the new background color. | 55 | | Transparent | Colored | The background color of the pixel that is about to be replaced is used as the new foreground color. | 56 | | Transparent | Transparent | The pixel is not rendered. 57 | 58 | ## Animations 59 | bimg can support multiple frames per image file. Each frame is numerically indexed at the root of the table, along the metadata. This allows easy retrieval with `ipairs`. 60 | 61 | In the event multiple frames are provided, the image is considered as an animation. Consequently, the `animated` boolean should be set to `true`, and the `secondsPerFrame` field is expected. If it is not present, the default value is set to `0.05` seconds. 62 | 63 | # Palettes 64 | Palettes allows the modification of the existing 16 ComputerCraft colors available in the `colors` API to custom RGB values, applied to the whole terminal at once. 65 | bimg allows the use of such palettes to render images more realistically, allowing for image effects (like dithering) to be applied. 66 | 67 | Palettes are formatted as a table, where the keys corresponds to the indexes of the ComputerCraft color values (ranged from 0 to 15), and the values the new RGB colors to apply. 68 | Values are contained themselves in a table, and can be either represented by a triplet of float numbers ranged from 0 to 1, each representing a color component, or a single integer number representing the three components at once: 69 | - `{ 1, 1, 0 }` sets the red and green components to full, outputting a bright yellow. 70 | - `{ 0xFFFF00 }` has the same effect, and will also provide a bright yellow. 71 | 72 | This allows both versions of `term.setPaletteColor()` to be supported through a single call, by unpacking the color table into the last argument: 73 | ```lua 74 | for color, tbl in pairs(palette) do 75 | term.setPaletteColor(2 ^ color, table.unpack(tbl)) 76 | end 77 | ``` 78 | 79 | Full example of a bimg color palette, featuring both color formats: 80 | ```lua 81 | { 82 | [14] = { 1, 0, 0 }, 83 | [13] = { 0, 1, 0 }, 84 | [11] = { 0x0000FF }, 85 | [7] = { 0.5, 0.5, 0.5 } 86 | } 87 | ``` 88 | 89 | If palettes are both defined in the metadata and in a frame, the palette in the frame takes higher precedence over the one defined in the metadata. Colors that are defined in the metadata palette but not in the frame palette are still applied. 90 | 91 | In the example below, both colors are modified and applied when rendering the frame: 92 | ```lua 93 | -- In metadata 94 | palette = { 95 | [14] = { 0xFF0000 } 96 | } 97 | 98 | -- In frame 99 | palette = { 100 | [11] = { 0x0000FF } 101 | } 102 | ``` 103 | --------------------------------------------------------------------------------