Skip to main content

fSpy Importer

ADDON
📖3 min read
Latest Version: 2.2
Perfect Photo and Camera Match with fSpy and Blender by chippwalters
1 / 2
Looking for the fSpy application?

This page covers the Blender importer addon. The standalone fSpy application (used to create the .fspy project files) has its own page: fSpy (standalone tool).

Introduction​

This addon imports project files generated by the standalone fSpy application. fSpy is an open-source tool that calculates camera parameters (focal length, orientation, position) from a single image. It serves investigators who match a Blender camera to a source photo using vanishing-point perspective solving.

Key Takeaways​

Project Import

Imports .fspy project files, transferring all calculated camera data into Blender.

Background Setup

Automatically sets up the reference image as a camera background, ready for modeling.

Resolution Match

Sets the Blender render resolution to match the dimensions of the original image.

Installation​

  1. Download the addon zip from the official GitHub repository.
  2. Go to Edit > Preferences > Add-ons.
  3. Click Install and select the zip file.
  4. Enable the addon.

Version 1.0.3; declared minimum Blender 2.80.

Blender 4.2 and later: the official importer is a legacy add-on (last release 2019) and does not install through the Extensions platform. Use the community fSpy NG fork, which packages the importer for the newer versions.

Usage​

Create the fSpy project· fSpy app

In the standalone fSpy application, load the source photo and define the perspective lines (vanishing points) to calculate the camera.

Import into Blender· File menu

Go to File > Import > fSpy (.fspy) and select your project file. Blender creates a camera with the correct position, orientation, and focal length.

Verify against the source· viewport

The reference image appears as the camera background at the original resolution. Check that model geometry aligns with the image.

In an Investigation​

What to document when using fSpy

In Your Method Section​

  • The source photo: filename, capture metadata, and origin.
  • The .fspy project file itself, the fSpy version used, and how many vanishing points you defined.
  • The resulting camera parameters: focal length, position, orientation.
  • Any real-world reference dimensions you supplied (e.g. a door frame) and where that measurement came from.

In Your Decision Log​

  • Why 2 or 3 vanishing points were available in the scene, and which lines you chose (parallel, straight, clearly visible).
  • Why the reference dimensions you entered are trustworthy: measured on site, standard sizes, or manufacturer specs.
  • Any lines you rejected and why: occluded, curved, ambiguous.

Verification​

Re-check the match in Blender: the camera's background image must align with known verticals and horizontals, and modeled geometry with known real-world sizes (a door, a window) must land at the correct scale in the photo. Archive the .fspy file and a screenshot of the matched viewport.

Example Methodology Statement​

"Camera perspective was matched to the source photograph with fSpy (3 vanishing points) and the official Blender importer (v1.0.3). Scale was set with a reference object measured on site. The matched camera parameters and the .fspy project file are archived as evidence."

Limitations​

  • Requires the separate fSpy application to create the project file. The addon is the importer only.
  • Best results come from photos with clear parallel lines (building corners); scenes without them solve poorly.
  • Consider the standalone fSpy tool page when you need to work solely outside Blender.

Resources​