PyStasm Documentation¶
Python wrapper for finding features in faces.
Stasm is a C++ software library for finding features in faces. For more information, visit http://www.milbo.users.sonic.net/stasm/
A minimal example with PyStasm looks like this:
import os.path
import cv2
import stasm
path = os.path.join(stasm.DATADIR, 'testface.jpg')
img = cv2.imread(path, cv2.IMREAD_GRAYSCALE)
if img is None:
print("Cannot load", path)
raise SystemExit
landmarks = stasm.search_single(img)
if len(landmarks) == 0:
print("No face found in", path)
else:
landmarks = stasm.force_points_into_image(landmarks, img)
for point in landmarks:
img[round(point[1])][round(point[0])] = 255
cv2.imshow("stasm minimal", img)
cv2.waitKey(0)
This produces the following image, showing the highlighted facial landmarks:
Functions¶
-
stasm.init(datadir=stasm.DATADIR, trace=False) → None¶ Initialize Stasm.
Parameters: - datadir – Path to directory containing Haar cascade XML files.
- trace – Set to True to trace to stdout and stasm.log for debugging.
-
stasm.open_image(image, debugpath="", multiface=False, minwidth=10) → None¶ Load an image for processing with Stasm.
Parameters: - image – ndarray containing gray image data.
- debugpath – Image file location used for debugging.
- multiface – Only search for one face if False; allow multiple faces if True.
- minwidth – Minimum face width, as a percentage of image width.
-
stasm.search_auto() → numpy.ndarray¶ Call repeatedly to find all faces.
Returns: ndarray with shape (stasm.NLANDMARKS, 2) containing face landmarks as [x,y] pairs, or empty ndarray if none found.
-
stasm.search_single(image, debugpath="", datadir=stasm.DATADIR) → numpy.ndarray¶ Opens and searches image for a single face.
Parameters: - image – ndarray containing gray image data.
- debugpath – Image file location used for debugging.
- datadir – Path to directory containing Haar cascade XML files.
Returns: ndarray with shape (stasm.NLANDMARKS, 2) containing face landmarks as [x,y] pairs, or empty ndarray if none found.
-
stasm.search_pinned(pinned, img, debugpath="") → numpy.ndarray¶ Find landmarks with no OpenCV face detection. Call after pinning some points.
Parameters: - pinned – ndarray containing pinned points as [x,y] pairs.
- img – ndarray containing gray image data.
- debugpath – Image file location used for debugging.
Returns: ndarray with shape (stasm.NLANDMARKS, 2) containing face landmarks as [x,y] pairs, or empty ndarray if none found.
-
stasm.lasterr() → str¶ Get last stasm error.
Returns: String describing last error.
-
stasm.force_points_into_image(landmarks, width, height) → numpy.ndarray¶ Force landmarks into image boundary.
Parameters: - landmarks – ndarray containing landmarks as [x,y] pairs.
- img – ndarray containing image to force points to.
Returns: ndarray containing landmarks within image boundary.
-
stasm.convert_shape(landmarks, format) → numpy.ndarray¶ Convert stasm.NLANDMARKS points to external format.
Parameters: - landmarks – ndarray containing landmarks as [x,y] pairs.
- format – One of the following options: stasm.SHAPE17, stasm.BIOID, stasm.AR, stasm.XM2VTS, stasm.MUCT76
Returns: ndarray containing landmarks in specified format.
Notes
Any number of points can be supplied if stasm.SHAPE17 is specified as the format type. For all others, landmarks must contain exactly 77 points or convert_shape will return an empty ndarray.