pyux.identify_face

Identifies the face of a part under a given viewport position and returns its geometry as a 2D polygon (with optional holes) in local coordinates.

This function is located in the pyux module.

pyux.identify_face is intended for use inside a graphics event handler (e.g. one registered via pyux.set_on_left_click_handler). The handler receives the current mouse position in viewport coordinates and can forward it to identify_face to identify the face that the user is pointing at, including its polygon outline.

result = pyux.identify_face(mouse_vp [,snap_parts [,no_snap_parts]])

Parameter	Type	Description
mouse_vp	{x, y}	Viewport coordinates of the pick position (typically passed in from the event handler).
snap_parts	{element_handle, ...}	Optional. Restricts the pick to faces of these parts only.
no_snap_parts	{element_handle, ...}	Optional. Excludes these parts from the pick.

Return value

Type	Description
result	{coos = {x,y,z}, normal = {x,y,z}, part = element_handle, polygon = {polygon_ex = {{loop_points_1}, ...}}}

Notes:

• The function performs a single identification at the given viewport position. To pick interactively, register an event handler with pyux.set_on_left_click_handler and call identify_face from inside it.
• The returned loop coordinates lie on the picked face's plane. Use normal together with any point of the polygon (for example its first vertex) to set up a local 2D coordinate system on that face.
• If the cursor is over empty space or over a part edge without a clear face hit, the returned table will lack the polygon field; the caller should treat that as a cancelled pick.

Example:

-- Inside a modal dialog: a "Pick face" button that lets the user click
-- a face and then logs its outline to the status bar.
local pick_btn = dialog:create_button(1, pyloc "Pick face")
pick_btn:set_on_click_handler(function()
    pyux.set_on_left_click_handler(function(mouse_vp)
        local result = pyux.identify_face(mouse_vp)
        pyux.set_on_left_click_handler(nil)

        if result and result.polygon and result.polygon.polygon_ex then
            local outer_loop = result.polygon.polygon_ex[1][1]
            pyio.message(string.format("Outer loop has %d vertices",
                #outer_loop))
        end
    end)
end)

Version Support:

Minimum PYTHA Version: V27

See also:

pyux, pyux.identify_part, pyux.identify_plane, pyux.set_on_left_click_handler, pytha.create_polygon_ex