{"id":17798842,"url":"https://github.com/ameobea/three-hex-tiling","last_synced_at":"2025-04-09T21:21:54.802Z","repository":{"id":174837315,"uuid":"652554044","full_name":"Ameobea/three-hex-tiling","owner":"Ameobea","description":"Adds support for hiding repeating texture patterns to Three.JS","archived":false,"fork":false,"pushed_at":"2025-02-18T01:11:11.000Z","size":807,"stargazers_count":77,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-02T19:08:11.702Z","etag":null,"topics":["glsl","glsl-shaders","hex-tiling","shaders","texture","texture-synthesis","threejs"],"latest_commit_sha":null,"homepage":"https://three-hex-tiling.ameo.design/","language":"TypeScript","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/Ameobea.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":"2023-06-12T10:00:52.000Z","updated_at":"2025-03-26T07:01:01.000Z","dependencies_parsed_at":"2023-11-15T10:26:32.947Z","dependency_job_id":"d899747a-ccb0-4109-bb7b-70f77f1b673c","html_url":"https://github.com/Ameobea/three-hex-tiling","commit_stats":{"total_commits":12,"total_committers":1,"mean_commits":12.0,"dds":0.0,"last_synced_commit":"0ded73ee9052cd8513c6a29e141798d5a27b92ad"},"previous_names":["ameobea/three-hex-tilebreaking","ameobea/three-hex-tiling"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ameobea%2Fthree-hex-tiling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ameobea%2Fthree-hex-tiling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ameobea%2Fthree-hex-tiling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ameobea%2Fthree-hex-tiling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ameobea","download_url":"https://codeload.github.com/Ameobea/three-hex-tiling/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248112571,"owners_count":21049673,"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":["glsl","glsl-shaders","hex-tiling","shaders","texture","texture-synthesis","threejs"],"created_at":"2024-10-27T12:01:36.430Z","updated_at":"2025-04-09T21:21:54.759Z","avatar_url":"https://github.com/Ameobea.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `three-hex-tiling`\n[![npm version](https://img.shields.io/npm/v/three-hex-tiling.svg?style=flat-square)](https://www.npmjs.com/package/three-hex-tiling)\n[![twitter](https://flat.badgen.net/badge/twitter/@ameobea10/?icon\u0026label)](https://twitter.com/ameobea10)\n\nExtends built-in Three.JS materials to support infinite, non-repeating, seamless texture tiling.\n\n![Screenshot showing comparison between a repeating seamless rock texture with and without three-hex-tiling.  The image is divided in half horizontally by a gray bar.  The left side is labeled \"baseline\" and shows a gray rock-like texture that clearly repeats, resulting in an artifical grid-like pattern.  The right side has the same rock texture but without any visible tiling and is labeled three-hex-tiling.](https://i.ameo.link/bpu.jpg)\n\nLive interactive demo: \u003chttps://three-hex-tiling.ameo.design/\u003e\n\n## Installation\n\n`npm install three-hex-tiling`\n\nThen, to enable it, just add this to your project as early as possible:\n\n```ts\nimport 'three-hex-tiling';\n```\n\nThis import will patch Three.JS's shaders and materials to support the hex tiling algorithm and it will extend the types for the patched materials with parameters to control it.\n\n### Three.JS Version Support\n\nThis library has been tested with Three.JS versions `0.151` through `0.173`.  Although it may work with other versions, support is not guaranteed.\n\n## Usage\n\nAfter adding the `three-hex-tiling` import at the top of your project, a new `hexTiling` parameter is added to the parameters of supported materials.  If your project uses TypeScript, these should be included in the types you see when creating those materials.\n\nBy setting the `hexTiling` property when creating a material, hex tiling will be enabled for that material.  It is disabled by default.\n\n```ts\nconst mat = new THREE.MeshStandardMaterial({\n  map: myTexture,\n  normalMap: myTextureNormalMap,\n  roughnessMap: myTextureRoughnessMap,\n  hexTiling: {\n    // default values shown\n    patchScale: 2,\n    useContrastCorrectedBlending: true,\n    lookupSkipThreshold: 0.01,\n    textureSampleCoefficientExponent: 8,\n  }\n});\n```\n\nHex tiling cannot be enabled or disabled after a material is created, but the values of individual parameters can be changed dynamically:\n\n```ts\nmat.hexTiling.patchScale = newPatchScale;\n```\n\n### Texture Scaling\n\nWhen enabling hex tiling for a material, you may find that your textures need a scale adjustment to look optimal.  This can be done using built-in Three.JS texture scaling support:\n\n```ts\nmyTexture.scale.set(1.5, 1.5);\nmyTextureNormalMap.scale.set(1.5, 1.5);\nmyTextureRoughnessMap.scale.set(1.5, 1.5);\n\nmyTexture.needsUpdate = true;\nmyTextureNormalMap.needsUpdate = true;\nmyTextureRoughnessMap.needsUpdate = true;\n```\n\n### Supported Textures\n\nTextures used with `three-hex-tiling` must be seamless - meaning that there are no sharp cutoffs when the texture is tiled.  There's a good chance your textures are seamless already and if they aren't, it will be obvious.\n\n### Supported Materials\n\nThe following materials are currently supported for use with `three-hex-tiling`:\n\n * `MeshStandardMaterial`\n * `MeshPhysicalMaterial`\n\nYou can still use all of the other materials that Three.JS provides, but they will not have support for hex tiling.\n\n### Supported Maps\n\nIn addition to the base texture/color of a material provided in the `map` property, `three-hex-tiling` supports with the following maps:\n\n * `normalMap`\n * `roughnessMap`\n * `metalnessMap`\n\n## Config Options\n\n`three-hex-tiling` accepts the following configuration properties in the `hexTiling` object:\n\n### `patchScale: number`\n\n- **Description**: Scale factor for the hexagonal tiles used to break up the texture. This parameter is crucial in controlling the hex tiling's appearance and requires adjustment for each texture.\n- **Default**: `2`\n- **Range**: `[0, Infinity]`, typically between 0.1 and 8. Optimal values depend on the texture and desired effect.\n- **Behavior**: Larger values create smaller hexagonal tiles, resulting in more texture breakup.\n\n| ![Screenshot of a black and red lava-like texture with three-hex-tiling applied with a patch scale of 1](https://i.ameo.link/bp2.jpg) | ![Screenshot of a black and red lava-like texture with three-hex-tiling applied with a patch scale of 2](https://i.ameo.link/bp3.jpg) | ![Screenshot of a black and red lava-like texture with three-hex-tiling applied with a patch scale of 6](https://i.ameo.link/bp5.jpg) |\n|----------------------------------|----------------------------------|----------------------------------|\n| Patch Scale: 1                   | Patch Scale: 2                   | Patch Scale: 6                   |\n\n### `useContrastCorrectedBlending: boolean`\n\n- **Description**: Determines if contrast-corrected blending is used for texture samples. This method often enhances blending quality but might result in overly bright or dark patches in high-contrast textures.\n- **Default**: `true`\n- **Reference**: [ShaderToy Demo](https://www.shadertoy.com/view/4dcSDr)\n\n| ![Screenshot of a rocky/mineral-like texture with three-hex-tiling applied and contrast-corrected blending enabled](https://i.ameo.link/bp8.jpg)     | ![Screenshot of a rocky/mineral-like texture with three-hex-tiling applied and contrast-corrected blending disabled](https://i.ameo.link/bp9.jpg)      |\n|--------------------------------------|---------------------------------------|\n| Contrast-Corrected Blending: Enabled | Contrast-Corrected Blending: Disabled |\n\n### `lookupSkipThreshold: number`\n\n- **Description**: The minimum magnitude below which texture lookups are skipped, mainly for optimization purposes.\n- **Default**: `0.01`\n- **Range**: `[0, 1]` (but you'll probably always want to keep it \u003c0.1)\n- **Advice**: Usually doesn't require modification.\n- **Details**: The shader mixes up to three texture samples per fragment. Texture lookups with a final coefficient less than this threshold are skipped to reduce GPU memory bandwidth usage.\n\n### `textureSampleCoefficientExponent: number`\n\n- **Description**: The exponent for texture sample coefficients before comparison with `lookupSkipThreshold`. Adjusting this value affects shader efficiency and the visibility of hexagonal tile borders.\n- **Default**: `8`\n- **Range**: `(0, 64]`\n- **Advice**: The default value is suitable for most textures. Modification is usually unnecessary.\n- **Details**: Coefficients raised to this exponent modify the steepness of the threshold for skipping texture lookups. Higher exponents increase efficiency by reducing texture lookups, potentially making the shader more efficient.\n\n| ![Screenshot of a gray rock-like texture with three-hex-tiling applied with a texture sample coefficient exponent of 1](https://i.ameo.link/bpi.jpg) | ![Screenshot of a gray rock-like texture with three-hex-tiling applied with a texture sample coefficient exponent of 2](https://i.ameo.link/bph.jpg) | ![Screenshot of a gray rock-like texture with three-hex-tiling applied with a texture sample coefficient exponent of 8](https://i.ameo.link/bpg.jpg) |\n|----------------------------------|----------------------------------|----------------------------------|\n| Texture Sample Coefficient Exponent: 1    | Texture Sample Coefficient Exponent: 2    | Texture Sample Coefficient Exponent: 8    |\n\n## Performance\n\nThe hex tiling shader used by this library needs to make up to 3 texture fetches per map per fragment in order to function.\n\nUsually, this is fine and doesn't result in any noticeable performance hit.  But in some situations, hex tiling can create a significant amount of texture bandwidth usage on the GPU and impact performance on weaker devices.\n\n### Optimizing Performance\n\nThere are some ways to tune `three-hex-tiling` to lessen its performance impact:\n\n * Increase `textureSampleCoefficientExponent` and/or `lookupSkipThreshold`\n   * This directly reduces the average number of texture samples made per fragment, but it can make the borders between hex tiles more obvious.\n * Use a [depth pre-pass](https://cprimozic.net/blog/threejs-depth-pre-pass-optimization/) to your scene to reduce the number of calls to the fragment shader.\n   * For some scenes, especially those with high overdraw, this can be a big win\n * Reduce the number of maps used by your material\n * Reduce the size of textures used or use [compressed textures](https://threejs.org/docs/#api/en/textures/CompressedTexture)\n\n## Implementation Details\n\nThe hex tiling shader itself is adapted from [a Shadertoy](https://www.shadertoy.com/view/MdyfDV) by [Fabrice Neyret](http://evasion.imag.fr/Membres/Fabrice.Neyret/).\n\n`three-hex-tiling` works by modifying Three.JS's shaders directly, patching in the hex tiling algorithm and conditionally enabling it for materials that opt in.  Materials that do not explicitly set `hexTiling` will work normally.\n\nIn addition to patching the shaders, it also installs a custom [`onBeforeCompile`](https://threejs.org/docs/#api/en/materials/Material.onBeforeCompile) callback on materials.  If you make use of `onBeforeCompile` in your own code, there's a good chance that `three-hex-tiling` will interfere with it and cause problems.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameobea%2Fthree-hex-tiling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fameobea%2Fthree-hex-tiling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameobea%2Fthree-hex-tiling/lists"}