Object Call Closest Point On Mesh

ObjectCall_ClosestPointOnMesh is one of the more genuinely useful geometry primitives buried in Avatar Graph's (avatechai/avatar-graph-comfyui) tail of auto-generated Blender API wrappers. The pack's headline job is rigging a still character portrait into a live, blinking, lip-syncing 2D avatar; this node isn't part of that documented workflow, but the operation it wraps - find the nearest surface point on a mesh - is exactly the kind of thing an image-derived-mesh pipeline like this one would eventually need.

How it works

It maps to Object.closest_point_on_mesh(origin, distance). Blender's docs describe it plainly: "find the nearest point on the object's mesh." Give it a 3D origin point, and (called on a mesh object) it searches the mesh surface for whatever point on it is closest to that origin, within an optional search radius.

Why you'd reach for it

Think facial landmarks or click-driven placement: if something upstream in your pipeline (image analysis, a manual click point, another object's position) gives you a 3D coordinate, and you need to snap it onto the actual surface of the character mesh - rather than leaving it floating in space - this is the primitive for that. It's a natural fit for a pack that builds meshes out of segmented image regions and then needs to place features (eyes, mouth) precisely on them.

Inputs and outputs

• BPY_OBJ (optional) - the mesh object to search.
• origin (optional, default null) - the 3D point you're searching from.
• distance (optional FLOAT, default 1.84467e+19) - the max search radius. That default isn't a meaningful physical distance; it's Blender's float-max sentinel value, effectively "search anywhere, no cap." Leave it alone unless you specifically want to limit how far the search reaches.

Output is a single BPY_OBJ, the object passed straight through - same pattern as the rest of this node family. In real Blender, closest_point_on_mesh() returns a result dict with a hit flag, the location found, the surface normal, the face index, and the distance. None of that comes out as a separate wire in this node's schema, so on its own, this node can trigger the search but can't hand you the answer.

Installing it

Avatar Graph depends on Blender's bpy module as a dependency, so expect a real install rather than a one-click drop-in. On Windows, use the author's bundled Python 3.10 environment (linked in their README), unzipped into your ComfyUI folder and run via the included .bat, then install "Avatar Graph" from ComfyUI Manager. On macOS/Linux, pin your ComfyUI environment to Python 3.10.x exactly - conda is the cleanest way (conda create --name comfyui python=3.10). Then cd ComfyUI/custom_nodes, git clone https://github.com/avatechai/avatar-graph-comfyui.git (their README's own manual-install command points at a stale org, avatechgg - the repo actually lives under avatechai). cd avatar-graph-comfyui && python -m pip install -r requirements.txt, then restart with python main.py --enable-cors-header (Mac: add --force-fp16 too). That CORS flag is what lets the hosted viewer at editor.avatech.ai talk to your local ComfyUI; skip it if you're exporting .glb/.gltf from Avatar Main Output instead.

Common issues

The Python-version pin trips up almost everyone first - bpy needs 3.10.x, nothing newer. Specific to this node: because the actual hit-test result isn't wired out, don't expect to chain the found location or normal into a downstream node directly from here alone. And since this node has no author documentation - it's absent from the README's node table - this write-up leans on Blender's own Object.closest_point_on_mesh() API docs, not anything Avatech published.