{"id":26576823,"url":"https://github.com/needle-engine/facefilter","last_synced_at":"2025-10-25T20:35:07.972Z","repository":{"id":283640358,"uuid":"951394882","full_name":"needle-engine/facefilter","owner":"needle-engine","description":"Face Filter support for Needle Engine: https://needle-face-filter-examples-z23hmxb18gxoo-latest.needle.run/","archived":false,"fork":false,"pushed_at":"2025-07-24T16:15:00.000Z","size":53893,"stargazers_count":20,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-24T21:51:44.936Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://needle-face-filter-examples-z23hmxb18gxoo-latest.needle.run/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/needle-engine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-03-19T15:56:54.000Z","updated_at":"2025-07-24T16:14:10.000Z","dependencies_parsed_at":"2025-07-09T13:48:04.937Z","dependency_job_id":"0a043fb6-e83e-4abd-b763-974fb3c03b3c","html_url":"https://github.com/needle-engine/facefilter","commit_stats":null,"previous_names":["needle-engine/facefilter"],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/needle-engine/facefilter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-engine%2Ffacefilter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-engine%2Ffacefilter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-engine%2Ffacefilter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-engine%2Ffacefilter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/needle-engine","download_url":"https://codeload.github.com/needle-engine/facefilter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/needle-engine%2Ffacefilter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267293761,"owners_count":24065321,"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-27T02:00:11.917Z","response_time":82,"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":"2025-03-23T03:34:11.377Z","updated_at":"2025-10-25T20:35:07.887Z","avatar_url":"https://github.com/needle-engine.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Needle Engine FaceFilter\n\nAdd face tracking to your [Needle Engine](https://needle.tools) projects with ease.  \nThis project contains the sourcecode for the facefilter package as well as an example Unity project (see [quickstart](#quickstart) below for how to get started without an editor)\n\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://www.npmjs.com/package/@needle-tools/facefilter\" target=\"_blank\"\u003e\u003cimg alt=\"NPM Version\" src=\"https://img.shields.io/npm/v/@needle-tools/facefilter\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/@needle-tools/facefilter\" target=\"_blank\"\u003e\u003cimg alt=\"NPM Last Update\" src=\"https://img.shields.io/npm/last-update/@needle-tools/facefilter\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n\n---\n\n\n\n# Features\n- Blendshape mesh face tracking\n- Texture face tracking with google/mediapipe canonical or procreate texture layouts (Use the `FaceMeshTexture` class)\n- Video face tracking: Play a video as a face texture (Use the `FaceMeshVideo` class)\n- Custom shader face meshes: Use custom materials on your face mesh (Use the `FaceMeshCustomShader` class)\n- Tracking for multiple faces at once (with smoothing)\n- *Can be used with Unity to create filters, animations, materials...*\n\n\n# Examples\n- [Example with Blendshapes on Stackblitz](https://stackblitz.com/edit/needle-engine-facefilter-blendshapes?file=src%2Fmain.ts)\n- [Example with Sunglasses on Stackblitz](https://stackblitz.com/edit/needle-engine-facefilter-glasses?file=src%2Fmain.ts)\n- [Example with Texture Mesh on Stackblitz](https://stackblitz.com/edit/needle-engine-facefilter)\n- [Example with ShaderToy on Stackblitz](https://stackblitz.com/edit/needle-engine-shadertoy-facefilter)\n- [Example without a bundler on Stackblitz](https://stackblitz.com/edit/needle-engine-facefilter-html?file=index.html)\n- [Example with HTML only 2D filter on Stackblitz](https://stackblitz.com/edit/needle-engine-facefilter-html-only?file=index.html) ([or github](https://github.com/needle-engine/facefilter/blob/main/package/examples/html/index.html))\n- [Example with HTML only 3D filter on Stackblitz](https://stackblitz.com/edit/needle-engine-facefilter-html-only-3d?file=index.html) ([or github](https://github.com/needle-engine/facefilter/blob/main/package/examples/html/model.html))\n- [Demo Video](https://github.com/user-attachments/assets/51300430-6290-4672-b2aa-f1e870b9e99c)\n\n\n## Quickstart\n\nRun `npm i @needle-tools/facefilter` in your web project   \n\nThen see the code below or [full examples](#examples):\n\n\n### Face Filter with Unity\n1) Clone this repository\n2) Open the Unity project at `Unity FaceFilter Example`\n3) Open the Example scene in Unity and click play\n\n**Note**: The Unity project uses Needle Engine 4.4 alpha.\n\n\n### Face Filter with HTML only\n\nSee full examples in [/examples/html/](/package/examples/)   \n\n#### Supported attributes\n\n| | |\n| -- | -- |\n| `face-filter` | URL to either a image or model file. Supported formats: `glTF`, `GLB`, `FBX`, `OBJ` **or 2D** `jpeg`, `jpg`, `png`, `webp` |\n| `face-filter-mask` | (optional, 2D only) URL to image file that will be used to mask out the face filter texture\n| `face-filter-layout` | (optional, 2D only) Either `procreate`, `mediapipe` or `canonical`. Default `mediapipe`\n| `face-filter-scale` | (optional, 3D only) Apply scale to the 3D face filter model (e.g. `face-filter-scale=\".5\"`)\n| `face-filter-offset` | (optional, 3D only) Offset the 3D face filter model (e.g. `face-filter-offset=\"0.0, 0.1, 0.1\"`)\n| `face-filter-max-faces` | (optional) How many faces should be tracked automatically. Default: `1`\n| `face-filter-show-video` | (optional) Should the camera videofeed be rendered in the background? Default: `true`. Can be set to `0` to hide the videofeed in the background.\n| `face-filter-video-selector` | (optional) HTML selector for a HTMLVideoElement. Useful if you want to render provide your own video element on the website elsewhere. If none is provided a hidden video element will be created automatically. \n\n\n#### HTML Example\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n      \u003cscript type=\"importmap\"\u003e\n          {\n            \"imports\": {\n              \"three\": \"https://cdn.jsdelivr.net/npm/@needle-tools/engine@4.4.0-alpha.5/dist/three.min.js\",\n              \"@needle-tools/engine\": \"https://cdn.jsdelivr.net/npm/@needle-tools/engine@4.4.0-alpha.5/dist/needle-engine.min.js\",\n              \"@needle-tools/facefilter\": \"https://cdn.jsdelivr.net/npm/@needle-tools/facefilter/dist/facefilter.min.js\"\n            }\n          }\n      \u003c/script\u003e\n      \u003cscript type=\"module\" src=\"https://cdn.jsdelivr.net/npm/@needle-tools/facefilter/dist/facefilter.min.js\"\u003e\u003c/script\u003e\n  \u003c/head\u003e\n\n  \u003cbody style=\"margin:0; padding:0;\"\u003e\n      \u003cneedle-engine\n          background-color=\"#ffffdd\"\n          face-filter=\"https://cdn.needle.tools/static/facefilter/facemask-template-procreate.webp\"\n          face-filter-mask=\"https://cdn.needle.tools/static/facefilter/facemask-occlusion-procreate.webp\"\n          face-filter-layout=\"procreate\"\n          \u003e\n      \u003c/needle-engine\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n[Open 2D Example](https://stackblitz.com/edit/needle-engine-facefilter-html-only?file=index.html) – \n[Open 3D Example](https://stackblitz.com/edit/needle-engine-facefilter-html-only-3d?file=index.html)\n\n\n\n### Face Mesh Texture Filter\n\n\n```ts\nimport { onStart } from '@needle-tools/engine';\nimport { FaceMeshTexture, NeedleFaceFilterTrackingManager } from '@needle-tools/facefilter';\n\nonStart(context =\u003e {\n  const scene = context.scene;\n\n  // Create a face filter tracking manager and add it to the scene\n  const filtermanager = new NeedleFaceFilterTrackingManager();\n  filtermanager.createMenuButton = true;\n  scene.addComponent(filtermanager);\n\n  // Creating a filter\n  const filter = new FaceMeshTexture({\n    layout: 'procreate', // we support both the google/mediapipe canonical layout and procreate/arkit layouts\n    texture: {\n      url: './assets/crocodile.webp', // provide a URL to the texture\n      // texture: \u003cyour texture\u003e // alternatively you can assign an existing texture directly\n    },\n  });\n  // Activate one of your filters\n  filtermanager.activateFilter(filter);\n});\n```\n[Open Example](https://stackblitz.com/edit/needle-engine-facefilter)\n\n\n\n### Face Mesh Blendshapes Filter\n\n\n```ts\nimport { onStart } from '@needle-tools/engine';\nimport { FaceMeshTexture, NeedleFaceFilterTrackingManager } from '@needle-tools/facefilter';\n\nonStart(context =\u003e {\n  const scene = context.scene;\n\n  // Create a face filter tracking manager and add it to the scene\n  const filtermanager = new NeedleFaceFilterTrackingManager();\n  filtermanager.createMenuButton = false;\n  scene.addComponent(filtermanager);\n\n  // Creating a filter using a GLB/glTF URL model that has blendshapes\n  const filter = await FaceFilterRoot.create('https://cloud.needle.tools/-/assets/Z23hmXBZWllze-ZWllze/file', {\n    scale: 0.5,\n    offset: { x: 0, y: 0.01, z: 0 },\n  });\n  if (filter) filtermanager.activateFilter(filter);\n});\n  ```\n[Open Example](https://stackblitz.com/edit/needle-engine-facefilter-blendshapes?file=src%2Fmain.ts)\n\n\n## Video\n\nhttps://github.com/user-attachments/assets/51300430-6290-4672-b2aa-f1e870b9e99c\n\n\n\n# Contributing\n\n⚠️ TODO\n\n\n# Contact\n\n\u003cb\u003e[needle](https://needle.tools)\u003c/b\u003e •\n[Twitter](https://twitter.com/NeedleTools) •\n[Forum](https://forum.needle.tools) •\n[Youtube](https://www.youtube.com/@needle-tools)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedle-engine%2Ffacefilter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneedle-engine%2Ffacefilter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneedle-engine%2Ffacefilter/lists"}