{"id":10918943,"url":"https://github.com/lisp-mirror/pngload","last_synced_at":"2025-09-17T08:32:30.101Z","repository":{"id":109683684,"uuid":"384268828","full_name":"lisp-mirror/pngload","owner":"lisp-mirror","description":"https://git.mfiano.net/mfiano/pngload (repository deleted)","archived":false,"fork":false,"pushed_at":"2021-07-08T23:11:28.000Z","size":277,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-18T22:30:57.017Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lisp-mirror.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2021-07-08T23:11:06.000Z","updated_at":"2024-07-18T00:12:49.000Z","dependencies_parsed_at":"2023-03-29T19:20:01.500Z","dependency_job_id":null,"html_url":"https://github.com/lisp-mirror/pngload","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisp-mirror%2Fpngload","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisp-mirror%2Fpngload/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisp-mirror%2Fpngload/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisp-mirror%2Fpngload/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lisp-mirror","download_url":"https://codeload.github.com/lisp-mirror/pngload/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233358288,"owners_count":18664159,"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":[],"created_at":"2024-06-08T14:20:06.520Z","updated_at":"2025-09-17T08:32:24.745Z","avatar_url":"https://github.com/lisp-mirror.png","language":"Common Lisp","readme":"# pngload\n\nA PNG (Portable Network Graphics) image format decoder.\n\n## Overview\n\npngload can be used to load images in the PNG image format, both from files on disk, or streams in\nmemory. This library was written out of frustration with png-read, which was the only native Common\nLisp code that supports PNG.\n\nWhat makes pngload different than png-read?\n\n### Speed\n\npngload is optimized for speed and portability across many different Common Lisp implementation and\narchitecture combinations. On 64-bit SBCL it is more than 3x faster than the png-read library when\ndecoding a particular large 4096x4096 RGBA image:\n\n- pngload: 0.901s\n- png-read: 3.058s\n\nNew in version 2.0: To overcome some performance bottlenecks, we wrote [our\nown](https://github.com/3b/3bz) decompressor, as the alternatives were too slow and not easily\noptimizable.\n\nAlso, we use the [mmap](https://github.com/Shinmera/mmap) library on operating systems that support\nit, with a fallback path when not supported.\n\n### Cleaner code\n\npngload should be a lot more hackable, and have more of an educational value than png-read, even\nafter adding lots of type declarations and restructuring the code away from its original cleanliness\nin favor of performance.\n\n### Full support for all chunks\n\nThe entire concrete syntax tree is parsed, and is visible as a slot in the returned `PNG` object\nwhen decoding an image. png-read does not support some of these. Additionally, human-readable\nformats are stored outside of the parse tree in the top-level object. For instance, if a chunk\nspecifying gamma correction is parsed, this will be stored as a floating-point value, rather than\nmultiplied by 100,000 and stored as an integer. Again, the raw data is stored in the `PARSE-TREE`\nslot of the returned object, should you ever need more.\n\n### Fully conforming with the PNG specification\n\npngload is able to load all images in [PNGSuite](http://www.schaik.com/pngsuite/) correctly.\npng-read claims that it can load them all, but they were not checked for validity.\n\n### Stores data in a format that is expected by [opticl](https://github.com/slyrus/opticl)\n\nopticl has supported pngload since its first release, which gives you faster PNG loading\nautomatically if you were already using opticl.\n\n### Support for PNG extensions\n\nNew in version 2.0, pngload supports [additional extension chunk\ntypes](http://ftp-osl.osuosl.org/pub/libpng/documents/pngextensions.html), such as EXIF information.\n\n### Optionally parse metadata only\n\npngload can optionally parse only the metadata, skipping decoding completely, in order to quickly\nretrieve information about an image.\n\n### Optionally decode as a 1-dimensional array\n\nInstead of decoding to a format which is compatible with opticl, pngload can now decode to a flat\n1-D array. This is useful for OpenGL texture uploading and some other applications.\n\n### Optionally flip the Y axis\n\npngload can optionally flip the Y axis when decoding, for when the origin is expected to be at the\nbottom left instead of the top left, as with OpenGL texture rendering.\n\n### Optionally write to foreign memory\n\npngload can optionally write to foreign memory using static-vectors. This is useful when needing to\nefficiently pass a pointer to the image data with a foreign library, such as with OpenGL.\n\n## Install\n\n``` lisp\n(ql:quickload :pngload)\n```\n\n## Usage\n\nUsage is quite simple:\n\n```lisp\n(pngload:load-file #p\"/path/to/file.png\")\n```\n\nThis will return an object which includes everything you would need to render the image data, or\nquery it for other useful data.\n\nAdditionally, you may load a PNG datastream from a Common Lisp stream with:\n\n```lisp\n(pngload:load-stream stream)\n```\n\nBoth `LOAD-FILE` and `LOAD-STREAM` accept an optional keyword argument, which can be used to disable\nthe slow process of decoding the image data. This can be used to very quickly get information about\nthe file, including but not limited to, the dimensions, last modification date, or palette\ninformation. Image data will be unavailable with this option, obviously. To use this fast reading\nmethod:\n\n```lisp\n(pngload:load-file #p\"/path/to/file.png\" :decode nil)\n```\n\nor:\n\n```lisp\n(pngload:load-stream stream :decode nil)\n```\n\nAdditionally, both `LOAD-FILE` and `LOAD-STREAM` may take the following keyword arguments:\n\n`FLATTEN` when non-NIL, will decode the image data to a 1-dimensional array, rather than the default\nmethod which is to be compatible with opticl.\n\n`FLIP-Y` when non-NIL, will flip the pixels on the Y axis, for when the origin is expected to be at\nthe bottom/left instead of the top/left.\n\n`STATIC-VECTOR` when non-NIL, will decode to foreign memory. It is up to the user to free memory\nwhen they are finished with it. Alternatively, you can use `WITH-PNG-IN-STATIC-VECTOR` which will\nautomatically free the memory for you.\n\n### Querying Metadata\n\nNew in version 2.0, pngload has a unified API for querying different metadata that may be stored in\na PNG datastream. The `get-metadata` method can be used to query any metadata available. It accepts\na PNG object, which is returned by `load-file` or `load-stream` as per the above, as well as a key\nidentifying the type of metadata you want to query. If a PNG datastream does not have the metadata\nrequested, NIL will be returned. The following keys are recognized:\n\n#### `:width`\nThe image width in pixels. This is the same as `(width png)` and is only for convenience.\n\n#### `:height`\nThe image height in pixels. This is the same as `(height png)` and is only for convenience.\n\n#### ``:bit-depth`\nThe number of bits per sample. This is the same as `(bit-depth png)` and is only for convenience.\n\n#### `:color-type`\nThe color type of the image. This is the same as `(color-type png)` and is only for convenience. One\nof the following is returned:\n- `:indexed-colour`: each pixel consists of an index into a palette.\n- `:greyscale`: each pixel consists of a single sample: grey.\n- `:greyscale-alpha`: each pixel consists of two samples: grey and alpha.\n- `:truecolour`: each pixel consists of three samples: red, green, and blue.\n- `:truecolour-alpha`: each pixel consists of four samples: red, green, blue,\n  and alpha.\n\n#### `:compression-method`\nThe method used to compress image data chunks. For standard PNG, this can only be `:zlib`. This will\nreturn `:unknown` if any other compression scheme was used.\n\n#### `:interlace-method`\nThe interlacing method. For standard PNG, this can be either `:null` or `:adam7`. This will return\n`:unknown` if any other interlacing method was used.\n\n#### `:filter-method`\nThe filtering method used to decode the image. For standard PNG, this can only be `:standard`. This\nwill return `:unknown` if any other filter method was used.\n\n#### `:palette`\nThe palette of an `:indexed-colour` image. This will return a 2-dimensional array of `(color-count\n3)` representing the red, green, and blue values of each indexed color in the palette.\n\n#### `:white-point`\nThe CIE 1931 reference white point. Returns two floating point values for the X and Y values.\n\n#### `:chromaticity-red`\nThe CIE 1931 primary red chromaticity. Returns two floating point values for the X and Y values.\n\n#### `:chromaticity-green`\nThe CIE 1931 primary green chromaticity. Returns two floating point values for the X and Y values.\n\n#### `:chromaticity-blue`\nThe CIE 1931 primary blue chromaticity. Returns two floating point values for the X and Y values.\n\n#### `:gamma`\nThe gamma adjustment for the desired display output intensity. Returns a floating point value.\n\n#### `:color-profile`\nThe ICC color profile of the image. Returns a octet vector to be decoded by any application wishing\nto make use of this.\n\n#### `:significant-bits`\nThe original number of sample significant bits. Returns multiple values; one for each color channel.\n\n#### `:srgb-rendering-intent`\nSpecifies how the samples should be displayed in the sRGB color space. This can be one of the\nfollowing:\n- `:perceptual`: for images preferring good adaptation to the output device gamut at the expense of\n  colorimetric accuracy, such as photographs.\n- `:relative-colorimetric`: for images requiring colour appearance matching (relative to the output\n  device white point), such as logos.\n- `:saturation`: for images preferring preservation of saturation at the expense of hue and\n  lightness, such as charts and graphs.\n- `:absolute-colorimetric`: for images requiring preservation of absolute colorimetry, such as\n  previews of images destined for a different output device (proofs).\n\n#### `:background-color`\nThe default background colour to present the image against. Returns 3 values; the red, green, and\nblue values.\n\n#### `:histogram`\nThe approximate usage frequency of each colour in the palette. Returns an association list mapping\neach palette color as a vector of 3 components to their frequencies.\n\n#### `:transparency`\nThe transparency color of the image. For `:indexed-colour` images, this returns an association list\nmapping each palette color as a vector of 3 components their transparency value. For `:truecolour`\nimages, this returns 3 values; the red, green, and blue sample value of the transparency color. For\n`:greyscale` images, this returns a single value for the transparency.\n\n#### `:pixel-dimensions`\nSpecifies the aspect ratio and physical size of image pixels. Returns a property list specifying the\nX and Y dimensions of each pixel, as well as a unit. `:unit` can be one of `:meter` or `:unknown`.\nIf `:unit` is `:unknown`, physical size of the pixels is not stored, and only the aspect ratio is\npresent.\n\n#### `:suggested-palettes`\nSome PNG images store a \"suggested palette\" chunk, which stores multiple palettes, histograms, and\ntransparency information together. This returns an association list mapping a palette name to a\nproperty list of suggested palette information.\n\n#### `:last-modified`\nThe timestamp the image was last modified. Returns an integer in the universal time format.\n\n#### `:text`\nArbitrary textual metadata stored in the PNG datastream. Returns a list of property lists.\n\n## License\n\nCopyright © 2017-2018 Michael Fiano \u003cmail@mfiano.net\u003e.\n\nLicensed under the MIT License.\n","funding_links":[],"categories":["Miscellaneous ##"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flisp-mirror%2Fpngload","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flisp-mirror%2Fpngload","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flisp-mirror%2Fpngload/lists"}