{"record":{"id":"6b081fddb3877064","repo":"lllyasviel/Fooocus","slug":"reference-pts-shape-must-be-k-2-or-2-k-and-k-2","errorCode":null,"errorMessage":"reference_pts.shape must be (K,2) or (2,K) and K>2","messagePattern":"reference_pts\\.shape must be \\(K,2\\) or \\(2,K\\) and K>2","errorType":"validation","errorClass":"FaceWarpException","httpStatus":null,"severity":"error","filePath":"extras/facexlib/detection/align_trans.py","lineNumber":194,"sourceCode":"        @face_img: output face image with size (w, h) = @crop_size\n    \"\"\"\n\n    if reference_pts is None:\n        if crop_size[0] == 96 and crop_size[1] == 112:\n            reference_pts = REFERENCE_FACIAL_POINTS\n        else:\n            default_square = False\n            inner_padding_factor = 0\n            outer_padding = (0, 0)\n            output_size = crop_size\n\n            reference_pts = get_reference_facial_points(output_size, inner_padding_factor, outer_padding,\n                                                        default_square)\n\n    ref_pts = np.float32(reference_pts)\n    ref_pts_shp = ref_pts.shape\n    if max(ref_pts_shp) < 3 or min(ref_pts_shp) != 2:\n        raise FaceWarpException('reference_pts.shape must be (K,2) or (2,K) and K>2')\n\n    if ref_pts_shp[0] == 2:\n        ref_pts = ref_pts.T\n\n    src_pts = np.float32(facial_pts)\n    src_pts_shp = src_pts.shape\n    if max(src_pts_shp) < 3 or min(src_pts_shp) != 2:\n        raise FaceWarpException('facial_pts.shape must be (K,2) or (2,K) and K>2')\n\n    if src_pts_shp[0] == 2:\n        src_pts = src_pts.T\n\n    if src_pts.shape != ref_pts.shape:\n        raise FaceWarpException('facial_pts and reference_pts must have the same shape')\n\n    if align_type == 'cv2_affine':\n        tfm = cv2.getAffineTransform(src_pts[0:3], ref_pts[0:3])\n    elif align_type == 'affine':","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/lllyasviel/Fooocus/blob/ae05379cc97bc4361ec8b4ec90193dab21be763f/extras/facexlib/detection/align_trans.py#L176-L212","documentation":"Before estimating the alignment transform, the code normalizes reference_pts to shape (K,2) with K>2 (at least 3 point pairs are needed for an affine/similarity transform). If the array's larger dim is <3 or the smaller dim is not exactly 2, the shape is not a valid 2-D point set and FaceWarpException is raised.","triggerScenarios":"Passing reference_pts as a flat array of 10 values, a (5,) vector, a (1,2) single point, or a 3-D array; i.e. anything whose shape doesn't reduce to (K,2)/(2,K) with K>=3.","commonSituations":"Loading reference landmarks from JSON/config that flattened them; slicing mistakes (pts[0] instead of pts); detector outputting a different landmark count or layout than expected.","solutions":["Reshape reference points to (K,2) with K>=3, e.g. np.array(pts).reshape(-1,2)","Prefer using the built-in get_reference_facial_points(...) output rather than hand-built arrays","Validate shape before calling: assert arr.ndim == 2 and min(arr.shape) == 2 and max(arr.shape) >= 3"],"exampleFix":"// before\nref = np.array([x1,y1,x2,y2,x3,y3,x4,y4,x5,y5])  # shape (10,)\n\n// after\nref = np.array([x1,y1,x2,y2,x3,y3,x4,y4,x5,y5]).reshape(5,2)","handlingStrategy":"type-guard","validationCode":"import numpy as np\nref = np.asarray(reference_pts, dtype=np.float32)\nassert ref.ndim == 2 and min(ref.shape) == 2 and max(ref.shape) >= 3, \\\n    'reference_pts must be (K,2)/(2,K) with K>2'","typeGuard":"def is_valid_point_set(pts) -> bool:\n    import numpy as np\n    a = np.asarray(pts)\n    return a.ndim == 2 and min(a.shape) == 2 and max(a.shape) >= 3","tryCatchPattern":null,"preventionTips":["Always reshape landmarks to (K,2) at the boundary","Generate reference points with get_reference_facial_points instead of hand-building","Add shape asserts in tests for landmark pipelines"],"tags":["facexlib","face-alignment","landmarks","shape-validation"],"backgroundTag":null,"analyzedSha":"ae05379cc97bc4361ec8b4ec90193dab21be763f","analyzedAt":"2026-08-15T04:23:59.533Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}