{"id":19571805,"url":"https://github.com/datocms/fast_thumbhash","last_synced_at":"2025-06-27T10:07:50.407Z","repository":{"id":151799379,"uuid":"623913130","full_name":"datocms/fast_thumbhash","owner":"datocms","description":"A highly optimized implementation of the ThumbHash algorithm, a compact representation of an image placeholder for a smoother loading experience","archived":false,"fork":false,"pushed_at":"2025-04-23T12:48:51.000Z","size":145,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-27T05:51:41.859Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datocms.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2023-04-05T10:59:52.000Z","updated_at":"2025-04-23T12:48:47.000Z","dependencies_parsed_at":"2024-11-11T06:21:07.188Z","dependency_job_id":"5151b5bf-03d4-4bb3-8e3b-4823ce3bf0a4","html_url":"https://github.com/datocms/fast_thumbhash","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/datocms/fast_thumbhash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datocms%2Ffast_thumbhash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datocms%2Ffast_thumbhash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datocms%2Ffast_thumbhash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datocms%2Ffast_thumbhash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datocms","download_url":"https://codeload.github.com/datocms/fast_thumbhash/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datocms%2Ffast_thumbhash/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262235790,"owners_count":23279566,"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-11-11T06:20:10.067Z","updated_at":"2025-06-27T10:07:50.380Z","avatar_url":"https://github.com/datocms.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--datocms-autoinclude-header start--\u003e\n\n\u003ca href=\"https://www.datocms.com/\"\u003e\u003cimg src=\"https://www.datocms.com/images/full_logo.svg\" height=\"60\"\u003e\u003c/a\u003e\n\n👉 [Visit the DatoCMS homepage](https://www.datocms.com) or see [What is DatoCMS?](#what-is-datocms)\n\n---\n\n\u003c!--datocms-autoinclude-header end--\u003e\n\n# FastThumbhash\n\n[![Ruby](https://github.com/datocms/fast_thumbhash/actions/workflows/main.yml/badge.svg)](https://github.com/datocms/fast_thumbhash/actions/workflows/main.yml)\n\nFastThumbhash is a Ruby gem that provides a highly optimized implementation of the [ThumbHash algorithm](https://evanw.github.io/thumbhash/), a compact representation of an image placeholder for a smoother loading experience.\n\nTo achieve these benefits, FastThumbhash is implemented as a Ruby C extension, which means that the core functionality of the ThumbHash algorithm is written in C for faster execution times compared to a pure Ruby implementation. This makes FastThumbhash ideal for applications or websites that require high-performance image processing.\n\n## Installation\n\nInstall the gem and add to the application's Gemfile by executing:\n\n    $ bundle add fast_thumbhash\n\nIf bundler is not being used to manage dependencies, install the gem by executing:\n\n    $ gem install fast_thumbhash\n\n## Usage\n\nUsing the ChunkyPNG library to process the image, this example shows how to generate a thumbhash that can be stored alongside an image as well as the method to convert the hash into a data string for the image placeholder.\n\n```ruby\nrequire \"fast_thumbhash\"\nrequire \"chunky_png\"\nrequire \"base64\"\n\n# load an image\nimage = ChunkyPNG::Image.from_file(\"image.png\")\n\n# convert the image into a base64-encoded thumbhash\nthumbhash = FastThumbhash.rgba_to_thumbhash(image.width, image.height, image.to_rgba_stream.unpack(\"C*\"))\n\nputs thumbhash # =\u003e \"rsYJLJZ4d4iAeIiAh5togIk3+A==\"\n\n# convert the thumbhash back to an RGBA stream\nwidth, height, rgba = FastThumbhash.thumbhash_to_rgba(thumbhash, max_size: 32)\n\n# generate a placeholder image based on thumbhash\nplaceholder = ChunkyPNG::Image.new(width, height, rgba.pack(\"C*\").unpack(\"N*\"))\n\n# save placeholder to file\noptions = { compression: Zlib::BEST_COMPRESSION, filtering: ChunkyPNG::FILTER_PAETH, interlace: false }\nplaceholder.save(\"placeholder.png\", options)\n\n# generate a DataURL string for the pleaceholder\nthumbhash_image_blob = \"data:image/png;base64,#{Base64.strict_encode64(thumbhash_image.to_blob(options))}\"\n```\n\n### Additional Options\n\nThis section covers additional options available for the `.thumbhash_to_rgba` method.\n\n##### `max_size`\n\nThe max_size option allows you to request a thumbnail up to the specified size. This is the suggested option for most use cases.\n\n```ruby\nw, h, rgba = described_class.thumbhash_to_rgba(thumbhash, max_size: 32)\n\nputs [w, h].inspect # =\u003e final image is [10, 32]\n```\n\n##### `homogeneous_transform` and `size`\n\nThe `homogeneous_transform` option allows you to apply a homogeneous transformation matrix when creating a thumbnail. The transformation matrix is a 3x3 array. This can be useful for applying roto-transformations to the thumbnail. The `size` option is useful to explicitly specify the width/height of the thumbnail when combined with the `homogeneous_transform` option to create a thumbnail with specific dimensions and transformations applied to it.\n\n\n```ruby\nw, h, rgba = described_class.thumbhash_to_rgba(\n  thumbhash,\n  size: [32, 32],\n  homogeneous_transform: [\n    [0.5, 0.0, 0.5],\n    [0.0, 1.0, 0.0],\n    [0.0, 0.0, 1.0]\n  ]\n)\n```\n\n##### `saturation`\n\nThe `saturation` option adjusts the saturation of the thumbnail's colors. It accepts a value in the range of -100 to +100. A value of -100 will result in a grayscale image.\n\n```ruby\nw, h, rgba = described_class.thumbhash_to_rgba(\n  thumbhash,\n  max_size: 32,\n  saturation: -100\n)\n```\n\n##### `fill_mode`\n\nThe `fill_mode` option specifies how to fill in any transparent areas in your image with a color of your choice. When `fill_mode` is `:solid`, you need to pass an additional `fill_color` option to specify the actual RGBA color to use. When `fill_mode` is `:blur`, the excess space will be filled with a blurred version of the original image itself. When `fill_image` is `:clamp`, the excess space is filled with extended pixels from the edge of the image.\n\n```ruby\nw, h, rgba = described_class.thumbhash_to_rgba(\n  thumbhash,\n  max_size: 32,\n  fill_mode: :solid,\n  fill_color: [255, 0, 0, 100]\n)\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Releasing a new version\n\nFirst update the FastThumbhash::VERSION, then run `rake release`.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/datocms/fast_thumbhash. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/datocms/fast_thumbhash/blob/master/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the FastThumbhash project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/datocms/fast_thumbhash/blob/master/CODE_OF_CONDUCT.md).\n\n\u003c!--datocms-autoinclude-footer start--\u003e\n\n---\n\n# What is DatoCMS?\n\n\u003ca href=\"https://www.datocms.com/\"\u003e\u003cimg src=\"https://www.datocms.com/images/full_logo.svg\" height=\"60\" alt=\"DatoCMS - The Headless CMS for the Modern Web\"\u003e\u003c/a\u003e\n\n[DatoCMS](https://www.datocms.com/) is the REST \u0026 GraphQL Headless CMS for the modern web.\n\nTrusted by over 25,000 enterprise businesses, agencies, and individuals across the world, DatoCMS users create online content at scale from a central hub and distribute it via API. We ❤️ our [developers](https://www.datocms.com/team/best-cms-for-developers), [content editors](https://www.datocms.com/team/content-creators) and [marketers](https://www.datocms.com/team/cms-digital-marketing)!\n\n**Why DatoCMS?**\n\n- **API-First Architecture**: Built for both REST and GraphQL, enabling flexible content delivery\n- **Just Enough Features**: We believe in keeping things simple, and giving you [the right feature-set tools](https://www.datocms.com/features) to get the job done\n- **Developer Experience**: First-class TypeScript support with powerful developer tools\n\n**Getting Started:**\n\n- ⚡️ [Create Free Account](https://dashboard.datocms.com/signup) - Get started with DatoCMS in minutes\n- 🔖 [Documentation](https://www.datocms.com/docs) - Comprehensive guides and API references\n- ⚙️ [Community Support](https://community.datocms.com/) - Get help from our team and community\n- 🆕 [Changelog](https://www.datocms.com/product-updates) - Latest features and improvements\n\n**Official Libraries:**\n\n- [**Content Delivery Client**](https://github.com/datocms/cda-client) - TypeScript GraphQL client for content fetching\n- [**REST API Clients**](https://github.com/datocms/js-rest-api-clients) - Node.js/Browser clients for content management\n- [**CLI Tools**](https://github.com/datocms/cli) - Command-line utilities for schema migrations (includes [Contentful](https://github.com/datocms/cli/tree/main/packages/cli-plugin-contentful) and [WordPress](https://github.com/datocms/cli/tree/main/packages/cli-plugin-wordpress) importers)\n\n**Official Framework Integrations**\n\nHelpers to manage SEO, images, video and Structured Text coming from your DatoCMS projects:\n\n- [**React Components**](https://github.com/datocms/react-datocms)\n- [**Vue Components**](https://github.com/datocms/vue-datocms)\n- [**Svelte Components**](https://github.com/datocms/datocms-svelte)\n- [**Astro Components**](https://github.com/datocms/astro-datocms)\n\n**Additional Resources:**\n\n- [**Plugin Examples**](https://github.com/datocms/plugins) - Example plugins we've made that extend the editor/admin dashboard\n- [**Starter Projects**](https://www.datocms.com/marketplace/starters) - Example website implementations for popular frameworks\n- [**All Public Repositories**](https://github.com/orgs/datocms/repositories?q=\u0026type=public\u0026language=\u0026sort=stargazers)\n\n\u003c!--datocms-autoinclude-footer end--\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatocms%2Ffast_thumbhash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatocms%2Ffast_thumbhash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatocms%2Ffast_thumbhash/lists"}