Opus Motion ★ Star on GitHub

Image looks · perspective-flatten

Perspective flatten

An oblique broadcast-style photo of a pitch un-tilts smoothly (a true homography, ease-in-out) into a straight top-down chalk board — the photo fades as a dark board with chalk lines and a faint grid takes over, the players become ring marks at their real positions, and shot markers drop onto the board one after another. Give it src + imagePoints + boardPoints to flatten your own photo of a pitch, court, floor, desk or whiteboard.

A free, MIT-licensed image effect from the Opus Motion Library — 616 motions for Remotion, React and plain HTML.

Perspective flatten: three frames of the image effect, start, middle and end
Perspective flatten — start, middle and end of the 7.0-second motion.

What Perspective flatten is for

Turning any oblique photo into a map or plan: sports shot maps, floor plans from a room photo, a whiteboard photo straightened into a clean diagram, real-estate site plans. A strong "how did they do that" moment.

  • perspective
  • homography
  • flatten
  • top-down
  • map
  • plan
  • shot map
  • sports
  • pitch
  • floor plan
  • whiteboard
  • chalk
  • photo to diagram
  • markers
  • image

Details

Category
Image looks & photo effects
Length
7.0 s (210 frames at 30 fps)
Formats
16:9, 1:1, 9:16
Weight
medium
Transparent overlay
no
Seamless loop
no
Text props
label
Colour props
boardColor chalk background
Image props
src
Mood
photo, night
Roles
backdrop

Use Perspective flatten in Remotion, React or HTML

Remotion project

terminal
# copy this motion into your Remotion project
node cli/mgl.mjs add perspective-flatten --to ../my-app/src

# render an mp4 (run in the library folder)
node cli/mgl.mjs render perspective-flatten --props '{"label":"","boardColor":"#0C1411","chalk":"#F4F1E8","background":"#0C1411","src":""}'

# or export for apps / editors: mp4 | webm-alpha | prores-alpha | gif | png | poster
node cli/mgl.mjs export perspective-flatten --as mp4 --props '{"label":"","boardColor":"#0C1411","chalk":"#F4F1E8","background":"#0C1411","src":""}'

React / Next.js

tsx
import {MotionPlayer} from 'opus-motion-library/web';

<MotionPlayer
  motion="perspective-flatten"
  props={{
    label: '',
    boardColor: '#0C1411',
    chalk: '#F4F1E8',
    background: '#0C1411',
    src: '',
  }}
  playOnView
  loop="auto"
/>

Plain HTML / WordPress

html
<script src="opus-motion.element.js" defer></script>

<opus-motion motion="perspective-flatten"
  props='{"label":"","boardColor":"#0C1411","chalk":"#F4F1E8","background":"#0C1411","src":""}'>
</opus-motion>

Compose spec (multi-scene video)

json
{
  "width": 1920,
  "height": 1080,
  "fps": 30,
  "scenes": [
    {
      "motion": "perspective-flatten",
      "props": {
        "label": "",
        "boardColor": "#0C1411",
        "chalk": "#F4F1E8",
        "background": "#0C1411",
        "src": ""
      }
    }
  ]
}

Perspective flatten props

13 parameters — change any of them to make the motion yours.

PropDefaultWhat it does
src""optional photo in public/ — flattened with the homography from imagePoints → boardPoints (default: the built-in oblique pitch)
board"pitch"chalk board preset: pitch (105×68 m), court (28×15 m) or floor (12×8 m plan)
imagePoints[]photo control points as [x,y] fractions of the frame (≥ 4, same order as boardPoints); empty = built-in camera
boardPoints[]the same points in board units (metres for the presets); empty = corners, mid-line and quarter points
at0.7seconds before the flatten starts
dur1.2flatten duration in seconds (~0.9–1.4)
markers[{"board":[88,30],"color":"#FF5A4D","size":1.9,"label":"xG .31"},{"board":[94,36],"colo…dots that drop on the board: {board:[u,v] | img:[x,y], color, size (m), at (s), label}
label""board caption (default per preset)
boardColor"#0C1411"board background
chalk"#F4F1E8"chalk line colour
grid60grid cell in px at 1080p
showPlayerstruering marks at the photo's player positions after the flatten
background"#0C1411"colour outside the board

Notes & credits

Technique sources:

  • lemo-opuscar styles/telestrator/demo/index.html — shotMap / flatten mesh (MIT, LemoLab)
  • demo/tools/homography.py concept