{
  "__type": "IngestedDoc",
  "__tag": 4010,
  "_content": {
    "Notes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Warns": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Raises": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Yields": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Methods": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Returns": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Parameters",
          "__tag": 4026,
          "children": [
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "tf",
              "annotation": "Self or :class:`~.FailedEstimation`",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "An instance of the transformation if the estimation succeeded. Otherwise, we return a special "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "FailedEstimation"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": " object to signal a failed estimation. Testing the truth value of the failed estimation object will return "
                    },
                    {
                      "__type": "InlineCode",
                      "__tag": 4051,
                      "value": "False"
                    },
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": ". E.g."
                    }
                  ]
                },
                {
                  "__type": "Code",
                  "__tag": 4050,
                  "value": "tf = ProjectiveTransform.from_estimate(...)\nif not tf:\n    raise RuntimeError(f\"Failed estimation: {tf}\")",
                  "execution_status": null
                }
              ]
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Estimate the transformation from a set of corresponding points."
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Receives": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Warnings": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Attributes": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    },
    "Parameters": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Parameters",
          "__tag": 4026,
          "children": [
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "src",
              "annotation": "array_like of shape (N, 2)",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Source coordinates."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "dst",
              "annotation": "array_like of shape (N, 2)",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Destination coordinates."
                    }
                  ]
                }
              ]
            },
            {
              "__type": "DocParam",
              "__tag": 4016,
              "name": "weights",
              "annotation": "array_like of shape (N,), optional",
              "desc": [
                {
                  "__type": "Paragraph",
                  "__tag": 4045,
                  "children": [
                    {
                      "__type": "Text",
                      "__tag": 4046,
                      "value": "Relative weight values for each pair of points."
                    }
                  ]
                }
              ]
            }
          ]
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Extended Summary": {
      "__type": "Section",
      "__tag": 4015,
      "children": [
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "You can determine the over-, well- and under-determined parameters with the total least-squares method."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Number of source and destination coordinates must match."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "The transformation is defined as      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "X = (a0*x + a1*y + a2) / (c0*x + c1*y + 1)\nY = (b0*x + b1*y + b2) / (c0*x + c1*y + 1)",
          "execution_status": null
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "These equations can be transformed to the following form      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "0 = a0*x + a1*y + a2 - c0*x*X - c1*y*X - X\n0 = b0*x + b1*y + b2 - c0*x*Y - c1*y*Y - Y",
          "execution_status": null
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "which exist for each set of corresponding points, so we have a set of N * 2 equations. The coefficients appear linearly so we can write A x = 0, where      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "A   = [[x y 1 0 0 0 -x*X -y*X -X]\n       [0 0 0 x y 1 -x*Y -y*Y -Y]\n        ...\n        ...\n      ]\nx.T = [a0 a1 a2 b0 b1 b2 c0 c1 c3]",
          "execution_status": null
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "In case of total least-squares the solution of this homogeneous system of equations is the right singular vector of A which corresponds to the smallest singular value normed by the coefficient c3."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "Weights can be applied to each pair of corresponding points to indicate, particularly in an overdetermined system, if point pairs have higher or lower confidence or uncertainties associated with them. From the matrix treatment of least squares problems, these weight values are normalized, square-rooted, then built into a diagonal matrix, by which A is multiplied."
            }
          ]
        },
        {
          "__type": "Paragraph",
          "__tag": 4045,
          "children": [
            {
              "__type": "Text",
              "__tag": 4046,
              "value": "In case of the affine transformation the coefficients c0 and c1 are 0. Thus the system of equations is      "
            }
          ]
        },
        {
          "__type": "Code",
          "__tag": 4050,
          "value": "A   = [[x y 1 0 0 0 -X]\n       [0 0 0 x y 1 -Y]\n        ...\n        ...\n      ]\nx.T = [a0 a1 a2 b0 b1 b2 c3]",
          "execution_status": null
        }
      ],
      "title": [],
      "level": 0,
      "target": null
    },
    "Other Parameters": {
      "__type": "Section",
      "__tag": 4015,
      "children": [],
      "title": [],
      "level": 0,
      "target": null
    }
  },
  "_ordered_sections": [
    "Summary",
    "Extended Summary",
    "Parameters",
    "Returns",
    "Yields",
    "Receives",
    "Raises",
    "Warns",
    "Other Parameters",
    "Attributes",
    "Methods",
    "Notes",
    "Warnings"
  ],
  "item_file": "/dev/scikit-image/src/skimage/transform/_geometric.py",
  "item_line": 1075,
  "item_type": "classmethod",
  "aliases": [
    "skimage.transform.ProjectiveTransform.from_estimate"
  ],
  "example_section_data": {
    "__type": "Section",
    "__tag": 4015,
    "children": [],
    "title": [],
    "level": 0,
    "target": null
  },
  "see_also": [],
  "signature": null,
  "references": null,
  "qa": "skimage.transform._geometric:ProjectiveTransform.from_estimate",
  "arbitrary": [],
  "local_refs": [
    "dst",
    "src",
    "tf",
    "weights"
  ]
}