Skip to main content

fSpy

TOOL
📖8 min read
Latest Version: 1.0.3
Blender Camera Matching Techniques & Strategies: Manual, Dolly Zoom, FSPY & Perspective Plotter
1 / 2
Looking for the Blender add-on?

This page covers the standalone fSpy application. The Blender-side importer has its own page: fSpy Importer (add-on).

Alternative: Perspective plotter works inside Blender

fSpy runs outside Blender, so every photo means a round-trip. Perspective plotter does the same matching inside Blender, which suits investigations that handle a set of photos at once.

Introduction​

fSpy is a free, standalone program that analyzes a 2D image to determine the exact internal camera parameters (location, rotation, and lens data) for import into Blender. The process, known as camera matching[1], is the essential first step for reconstructing a scene or object from a single photograph. Investigators who must place a virtual camera exactly where the real one stood start here.

Key Takeaways​

VPs Alone Are Not Enough

Vanishing points fix the camera orientation. The Principal Point and Focal Length must be set separately, or the imported scene will be skewed or stretched.

Cropped Images Shift the Axes

If the source image was cropped, the Principal Point moves away from the image center. A misplaced Principal Point is the most common cause of misaligned coordinate axes.

Scale Comes From a Known Dimension

A photo carries no absolute size. Set the Reference Distance to a measurable object in the frame (a door, a vehicle, a piece of furniture) to make the Blender scene real-world scale.

Installation​

fSpy is a separate program from Blender. The Blender side needs the official importer add-on to read .fspy project files.

  1. Install fSpy. Download it from the official site[2]. Builds for Windows, macOS, and Linux are available under the GPL-3.0 license. The last stable release is 1.0.3 (January 2019); a 1.1.0 beta has been in progress on GitHub[3] since 2020.
  2. Install the Blender importer. Follow the fSpy Importer add-on page for the fSpy-Blender zip install, including the Blender 4.2 Extensions workaround.

Usage​

Set the perspective in fSpy· image loaded

Drag the photo onto the fSpy canvas. Choose the perspective type (1, 2, or 3 vanishing points), then align the red, green, and blue (if active) lines to parallel lines in the image. Hold Shift while dragging for precision. For 3-point perspective, set two VPs first, then switch Principal Point > From third vanishing point to activate the third axis.

Place the principal point· cropped images

3-point images: fSpy calculates it automatically (an orange circle appears). 1-point images: switch to Principal Point > Manual and drag the orange dot onto the single vanishing point. 2-point or cropped images: if the Z-axis does not align, switch to Manual and drag the dot vertically along the axis that has parallel lines until the geometry aligns. Check the coordinates to confirm the horizontal position is centered (0.5) where it should be.

Fix the focal length in Blender· the iterative step

Save the .fspy file and import it in Blender (File > Import > fSpy (.fspy)). A camera appears with the photo as its background. Add a simple primitive (a Circle or Cube) and align it to a known shape in the image, such as a round lamp base or a square window. In Camera Properties, switch Lens to Millimeters and raise or lower the focal length until the 3D shape matches the object in the image exactly.

Anchor origin and reference distance· real-world scale

Back in fSpy, move the Origin to a point on the floor level that corresponds to the center of your 3D scene. Change the Reference Distance axis (for example Y) to a real-world length (0.603 m for a dishwasher width) and match it to a visible object of that size. Save the project and re-import it in Blender. The scene is now scaled to real-world dimensions.

Quick reference​

Tips from the [official tutorial][4] and its [Blender Artists companion thread][5] for the video above.

StageTipWhere
fSpyUse precision mode: hold Shift while placing or adjusting lines to activate the zoom circle and slow mouse movement.Hold Shift while dragging lines.
fSpyDraw long lines: vanishing point lines drawn to the edges of the image give higher accuracy.Draw lines edge to edge.
fSpy1-point rule: the Principal Point must overlap the single vanishing point.Principal Point > Manual
fSpyFixing the Z-axis: if it is misaligned (common in 2-point perspective), drag the Principal Point vertically along the parallel lines.Drag orange dot vertically in Manual mode.
BlenderIterative FOV correction: match a 3D reference object against a real object of known shape in the background image.Camera Properties > Focal Length (mm)
BlenderConstrain movement: keep object moves on the working plane or axis to prevent accidental depth changes.G then Shift + Axis

In an Investigation​

Documentation: how to document fSpy

In Your Method Section​

Guidance: Describe the purpose, the tool version, and the input data.

  • Investigative Objective: To determine the intrinsic and extrinsic camera parameters from a single 2D image for spatial reconstruction.
  • Software Version: fSpy [Version] (e.g., 1.0.3) with Blender Importer [Version].
  • Input Data: Derived from [Image Filename] (Source Hash: [First 6 digits]).

In Your Decision Log​

Guidance: Record the specific procedural parameters and integrity checks.

  • Specific Settings: Vanishing Points ([1/2/3]), Principal Point ([Manual/Auto]), Reference Distance ([Axis] = [Value] meters).
  • Assumptions: Assumed the scene contained orthogonal parallel lines and the image had zero lens distortion.
  • Integrity Check: Verified that the Principal Point was correctly placed (especially for cropped images) to avoid skewed geometry.
  • Date Performed: [YYYY-MM-DD].

Verification & Mitigation​

Guidance: How did you verify accuracy and mitigate bias?

  • Verification: Imported the camera into Blender and overlaid geometric primitives (cubes, circles) on known features to confirm alignment.
  • Bias Mitigation: Used the longest possible lines in the image for vanishing points to minimize angular error.

Example Methodology Statement​

"To calibrate the camera parameters, fSpy (v1.0.3) was used on the source image [Hash: A1B2C3]. Vanishing points were established using [Feature X] and [Feature Y]. The scene scale was set using a reference measurement of [X.X] meters for the [Object]. The solution was verified in Blender by overlaying primitives on the [Verification Feature], confirming a match."

Into Blender​

fSpy outputs a .fspy project file: camera position, orientation, field of view, principal point, origin, and reference distance. The official importer add-on[6] reads it through File > Import > fSpy (.fspy) and creates a camera with the source image set as its background. The official format specification[7] shows a four-byte fspy header, the JSON camera state, and an embedded copy of the source image: one archived file carries the image with the camera solution.

Three caveats before you start modeling:

  • Scale is only as good as your reference distance. Without a known dimension in the frame the scene is arbitrary. Set it in fSpy before the final import.
  • fSpy assumes a rectilinear lens. Wide-angle and fisheye images carry barrel or pincushion distortion that breaks the match. Correct the distortion in the image first.
  • A single photo gives no Z coordinate. Anchor your modeling to the fSpy Origin (placed on a ground plane) and constrain movements to that plane.

Limitations​

  • fSpy cannot determine absolute scale without a known reference measurement in the image.
  • It assumes a rectilinear lens model. Significant lens distortion fails the match unless the image is pre-corrected.
  • A single 2D photo cannot provide all three coordinates. Anchor depth to the Origin and constrain movements in Blender.
  • fSpy ignores EXIF orientation[8]: phone photos can load rotated. Reset the EXIF flag, then rotate the pixels[9].
  • Known open bugs[10]: no startup on macOS Sequoia or Tahoe, and the reference distance can snap back to 4 m.
  • Development is stalled: no stable release since January 2019.
  • Prefer to stay inside Blender? Perspective plotter does the same job there (see the note at top).

How It Works​

fSpy reverse-engineers the camera from a single image using projective geometry. The logic that matters when you interpret its results:

  • Vanishing points define orientation. Lines that are parallel in 3D converge to a single point in the image. One to three such points, chosen from the scene's principal axes, fix how the camera is rotated relative to the scene.
  • The principal point defines the center. It is where the camera's optical axis crosses the image plane. For an unmodified image it sits at the image center; cropping or an off-center sensor moves it. Get it wrong and the Z-axis skews against the image.
  • Focal length comes from pairs of vanishing points. With two orthogonal directions, fSpy computes the focal length as the geometric mean of the per-axis estimates and converts it from the sensor width. A single vanishing point gives no focal length: in one-point mode you enter the focal length and the second-axis direction yourself. The result still carries your principal-point and no-distortion assumptions, so treat the reported field of view as a hypothesis and verify it against a shape of known size in Blender.
  • The reference distance anchors scale. A real-world length applied to a measurable segment in the image converts the abstract 3D solution into metered space.

For the full derivation (principal point, optical axis, the geometric-mean math, and why more vanishing points reduce error), see Camera Matching Strategies. Its video is first in the carousel above.

Resources​

Sources​

  1. fSpy basics, how camera matching and vanishing points work
  2. fSpy official site, download and import documentation
  3. fSpy source code, releases and GPL-3.0 license
  4. fSpy tutorial, official walkthrough of every option
  5. Complete fSpy tutorial (Blender Artists), companion to the Bartosz Pampuch video
  6. fSpy importer for Blender, official importer add-on repository
  7. fSpy project file format, official header, JSON state, embedded image
  8. Issue #57: image orientation incorrect after import, open EXIF bug
  9. Derotating image with EXIF orientation, workaround for the orientation bug
  10. Open issues on fSpy, current bug tracker