Skip to main content

fSpy

BEGINNER
📖8 min read

Introduction​

fSpy is a free, standalone program that analyzes a 2D image to determine the exact internal camera parameters (location, rotation, and lens data) which can then be imported into Blender. This process, known as camera matching, is an essential step for manually reconstructing a scene or object from a single photograph. Achieving a good match requires understanding and correctly setting all fSpy parameters, not just the vanishing points.

Key Features​

Perspective Calibration

Align 3D coordinate axes to the image using Vanishing Points (VPs) and ensure scene geometry follows the correct perspective relationships.

Principal Point Detection

Identify and set the Principal Point to correct for image cropping or off-center cameras; this is useful for accurate axis alignment.

Real-World Scaling

Anchor the scene with an origin and set a reference distance to scale the 3D model to real-world units.

Installation​

fSpy is a separate program from Blender, but it requires a Blender add-on to complete the process.

1. Install fSpy (Standalone Program):

  • Download and install the fSpy application from the official source.

2. Install the fSpy Add-on (Blender):

  • In Blender, navigate to Edit > Preferences.
  • Go to the Add-ons tab.
  • Search for the "fSpy" add-on and ensure it is checked and enabled. This allows Blender to import the .fspy project file.

Usage: Full Camera Matching Workflow​

The workflow is divided into three stages: fSpy setup, Focal Length correction in Blender, and Scene Scaling.

Stage 1: Initial Perspective Setup in fSpy​

  1. Load Image: Drag and drop your image onto the fSpy canvas.
  2. Determine Perspective Type: Analyze your image to determine if it has 1, 2, or 3 vanishing points.
  3. Align Vanishing Points (VPs):
    • Set the Number of Vanishing Points dropdown.
    • Align the red, green, and blue (if active) lines along parallel lines in the 3D scene (e.g., floor tiles, window frames). Hold Shift while dragging for precision.
    • For 3-point perspective, you must set 2 VPs first, then change Principal Point > From third vanishing point to activate the third axis.
  4. Align the Principal Point:
    • 3-Point Images: fSpy calculates this automatically (an orange circle appears).
    • 1-Point Images: Switch to Principal Point > Manual and drag the orange dot until it overlaps the single vanishing point.
    • 2-Point/Cropped Images: If the Z-axis doesn't align, switch to Manual mode. Drag the Principal Point vertically along the axis that has parallel lines until the geometry aligns, then check the coordinates to ensure the horizontal position is centered (0.5) if appropriate.

Stage 2: Focal Length Correction (The Iterative Step)​

The initial Field of View (FOV) is usually wrong, causing distortion. This needs to be fixed in Blender.

  1. Export Project: Save your file as a .fspy file.
  2. Import to Blender: In Blender, go to File > Import > fSpy (.fspy). A new camera object will be created with the image set as the background.
  3. Add Reference Shape: Add a simple primitive (e.g., a Circle or Cube) and align it to a corresponding known shape in the background image (e.g., a round lamp base or square window).
  4. Iterative Adjustment: Go to the Camera Properties (green camera icon). Under Lens, switch the unit to Millimeters (Focal Length).
    • Increase the Focal Length to decrease the FOV and reduce stretching.
    • Decrease the Focal Length to increase the FOV.
    • Adjust the value and reposition the 3D shape until it perfectly matches the shape in the image.

Stage 3: Scene Scaling​

  1. Anchor Origin: In fSpy, move the Origin (the center crosshair) to a point on the floor level that corresponds to the center of your 3D scene.
  2. Set Reference Distance: In the fSpy options, change the Reference Distance axis (e.g., Y) and set a real-world length (e.g., 0.603 m for a dishwasher width). Use the handles to match this distance to a visible object of that size in the image.
  3. Final Export: Save the .fspy project one last time. When you re-import or reload the project in Blender, the scene will now be scaled to real-world dimensions.

2. KEY POINTS​

  • Vanishing Points (VPs) are Insufficient: A good camera match requires not just aligning the VPs, but correctly setting the Principal Point and the Focal Length (or Field of View). Ignoring these may lead to distorted geometry.
  • The Principal Point Defines Perspective Center: The Principal Point is the projection of the camera's center onto the image plane. If the source image has been cropped or manipulated, this point shifts away from the image center, and a misplaced Principal Point is the most common cause of coordinate axis misalignment in the 3D scene.
  • Initial FOV is Often Wrong: The initial Field of View (FOV) calculated by fSpy is usually too large, leading to distorted proportions. The correct FOV/Focal Length needs to be found iteratively in Blender by matching known simple 3D shapes against objects in the background image.
  • 2D Photos Hide Depth: Since a 2D photo cannot provide all three coordinates (X, Y, Z), you must anchor your modeling process to the fSpy Origin (which should be placed on a ground plane) and constrain all subsequent movements in Blender to that known plane to avoid accidental changes to depth.
StageUseful TipsCommand/Location
fSpyUse Precision Mode: Hold Shift while placing or adjusting lines in fSpy to activate the zoom circle and slow mouse movement.Hold Shift while dragging lines.
fSpyDraw Long Lines: Draw vanishing point lines as long as possible (to the edges of the image) to achieve higher accuracy.Draw lines from image edge to image edge.
fSpy1-Point VP Rule: For 1-point perspective, the Principal Point must overlap the single Vanishing Point. Switch to Manual mode and drag the orange dot onto the VP.Principal Point > Manual
fSpyFixing the Z-Axis (Cropped Images): If the Z-axis is misaligned (common in 2-point perspective), drag the Principal Point vertically along the parallel lines (the axis without a VP) until the Z-axis aligns.Drag orange dot vertically in Manual mode.
BlenderIterative FOV Correction: Import the fSpy project into Blender, add a simple 3D reference object (e.g., Cube, Circle), and manually adjust the Camera Focal Length until the 3D object perfectly matches a real object of known shape in the background image.Camera Properties > Focal Length (mm)
BlenderConstrain Movement: In Blender, nearly every object movement should be constrained to the working plane or axis to prevent accidental depth changes (e.g., using G Shift + Z to move along the floor).G then Shift + Axis
BlenderTemporary Snapping: Press and hold Ctrl while dragging an object (G) to temporarily activate snapping without toggling the button on.Hold Ctrl while dragging (G).
BlenderMulti-Target Snapping: Hold Shift in Blender's snapping target menu to select multiple targets (e.g., Vertex + Face) simultaneously for a highly efficient workflow.Hold Shift in the Snapping dropdown.
BlenderLinked Duplicates: Use Alt + D (Linked Duplicate) instead of Shift + D (Regular Duplicate) for identical objects (like chairs). This allows you to align multiple perspective references simultaneously and ensures mesh changes are applied globally.Alt + D

How fSpy Works​

fSpy uses principles of projective geometry to reverse-engineer the camera parameters from a single 2D image. By identifying vanishing points and the principal point, it can infer the camera's orientation and lens characteristics. The key mathematical concepts include:

Summary​

fSpy is a powerful tool for visual investigation when used correctly. The core of the workflow involves three key steps: correctly establishing the Vanishing Points, precisely setting the Principal Point (especially for cropped images), and iteratively correcting the Focal Length in Blender using reference shapes. The resulting scene is a properly scaled 3D environment ready for accurate reconstruction and analysis.

Documentation for Methodology​

To ensure your work aligns with the Berkeley Protocol, use the following points to document your use of fSpy.

Methodology: 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 mitigate bias or verify accuracy?

  • 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.

Common Limitations​

  • Cannot determine absolute scale without a known reference measurement.
  • Assumes a rectilinear lens model; fails with significant barrel/pincushion distortion unless pre-corrected.

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."

Tags:
Last updated on by blender-visual-investigation