MTF_MAPPER(1)

📦 version 0.7.41, in ubuntu stonking

🌸 NAME 🌸

ok so bestie, gather round, because this one is mtf_mapper(1) — it computes the MTF50 edge sharpness measure in images. that's the whole vibe. sharp edges, measured, slayed. 💅

✨ SYNOPSIS ✨

mtf_mapper [OPTIONS] INPUT_IMAGE OUTPUT_DIR

🦋 DESCRIPTION 🦋

so what does mtf_mapper actually do? it computes the edge acuity (that's sharpness, bestie) of slanted edges in images. and like, it doesn't need you to hold its hand — it automatically detects dark rectangular objects on light backgrounds, then computes the MTF50 values across each of the edges. main character energy, honestly.

the output comes in several forms — go peek at the -p, -s, -a and -q output options for all of that. 💖

and if you wanna test mtf_mapper? you can generate images with rectangles containing known MTF50 values using mtf_generate_rectangle. perfect little control group, no cap.

👑 OPTIONS 👑

here's the whole menu, no skips, every single one, because we don't do "tl;dr" around here. 🫶

  • -t threshold, --threshold threshold — sets the dark object threshold, and the default is 0.55. you'll want lower values if your dark objects are actually light compared to the background — think gray rectangles instead of black rectangles, iykyk. and if MTF Mapper is acting like it can't see any dark objects at all, try lower values like 0.3 or even 0.2. 🙈
  • --threshold-window fraction — tells it what fraction of the smaller image dimension (height or width) gets used as the window size during the automatic thresholding that detects dark objects (that's the -t thing). default is 0.3333, which is chef's kiss when your test chart has a white background. BUT if your dark targets have some other chart feature hanging around them (looking at you, QA-62 Scanner targets 💀), try shrinking this fraction. picking a fraction roughly equal to the size of the dark target (as a fraction of image height) should do the trick.
  • -l, --linear — linear input mode, periodt. it assumes an 8-bit input image has a linear intensity scale. the default behaviour is to assume that 8-bit input images have an sRGB gamma intensity profile (approximately gamma 2.2).
  • --pixelsize size — drop your sensor's pixel size (pitch) here, in microns. heads up: this option implicitly switches the MTF50 output units (for some output types) to line pairs per mm, aka lp/mm. the default is cycles per pixel, aka c/p.
  • --bayer red|green|blue|none — process only the specified Bayer sites. this one is for bypassing the effects of Bayer demosaicing interpolation when you've got suitable raw images (like dcraw -d output, love that for us). ⚠️ if you specify this option on a demosaiced image you will not get the expected result — you must provide a raw image for this option to work correctly, fr fr. also keep in mind that Bayer red and blue each only cover 25% of the sensor, so your edges have to be 4 times longer to keep the same signal-to-noise ratio. minimum recommended edge lengths: 35 pixels for gray or interpolated images, 70 pixels for green Bayer sites, and 140 pixels for red and blue Bayer sites. and honestly, aim for edges of at least 200 pixels for best results on red and blue sites. and yes — see --cfa-pattern to specify the Bayer pattern of your raw image. 🎀
  • --cfa-pattern rggb|bggr|grbg|gbrg — picks the Bayer pattern to use whenever the --bayer option has been specified. the default is rggb, which appears to be the most popular choice amongst DSLRs. iconic of them.
  • --esf-model kernel|loess — choose which algorithm MTF Mapper uses to construct the Edge Spread Function (the ESF). the loess algorithm is the recommended one, unless you're trying to produce results that are compatible with older versions of MTF Mapper (pre-version 0.7.16) — and by "compatible" we mean "ahem, roughly similar is more like it". 😭
  • --single-roi — treats the entire input image as the region of interest (ROI). this is only intended for small cropped images containing just a single edge — typically when you cropped your ROI out of some larger image. use it if you're doing slanted-edge measurements with a backlit razor blade, or if you're working with an incompatible test chart (like an older ISO 12233 chart). this option has largely superseded the -b option. glow up. ✨
  • --zscale scale-factor — adjusts the minimum value of the z-axis scale of the 3D plots produced with the --surface output option. a value of 0 means the z-axis scale starts at zero, and 1.0 means the z-axis starts from the minimum MTF50 measurement (which really emphasizes those local differences).
  • --logfile filename — logger output gets written to filename in stead of standard out.
  • --gnuplot-width pixels — the width of images rendered by gnuplot. typically this affects the output images of --lensprofile, -s, and -p.
  • -b, --border — adds a white border of 100 pixels to the image. might be useful if your image contains only a single black target (a rectangle, say) with a thin white border, or if your image sides clip some of your black test chart targets. but real talk: this option is a kludge to fool MTF Mapper's automatic target detection, so you should not normally need it. also go see --single-roi for the correct way of dealing with single-edge images. 💀
  • --snap-angle angle — snaps all edge angles to angle. angles get snapped to the closest value modulo 90 degrees, so specifying an angle of 4 degrees will force edge orientations to one of these: 4, -4, 86, or 94 degrees. use this one with care, bestie — it's only appropriate if you're using synthetic images with a known edge orientation. 🙈
  • -g angle, --angle angle — only report MTF50 values on edges with an orientation of angle degrees, in raw output mode (-r).
  • --autocrop — automatically crops the input image to the chart area. the chart is assumed to be brighter than the background, and the automatic cropping will try to remove the darker background. this is mostly meant to speed up processing, and really should only be used if the background area is large compared to the test chart area.
  • --imatest-chart — automatically crops the input image so that the black bars at the top and bottom of Imatest-style charts (like SFRplus) are suppressed, which lets you fully automatically process all of the square targets found in the chart. you may wanna use a lower threshold value (-t) of 0.4 or even lower when using --imatest-chart, just to make sure all the square targets get detected. 🚫 and do not use this option with native MTF Mapper test charts.
  • --mtf contrast — by default MTF Mapper computes MTF50, i.e. the resolution (in lp/mm or cycles/pixel) at which the SFR curve first reaches a contrast of 50%. this option lets you change that target contrast value — compute MTF20, for example. valid contrast values are in the range [10, 90], and they'll be clamped to this range if necessary. this option affects all outputs, including the Annotated image, Profile, Grid and Focus position outputs; only the SFR outputs are unaffected. 👑
  • --gnuplot-executable filepath — specify the full path to the gnuplot executable. defaults to /usr/bin/gnuplot, which is usually correct on most Linux distributions.
  • -h — displays usage information. the classic. 🫶

Alright bestie, this is the glow-up section where you decide what MTF Mapper actually hands back to you. Different outputs, different files, different vibes — pick your fighter 💅

  • -a, --annotate — annotated output mode, iykyk. Turns on Annotate mode and mtf_mapper spits out a file called annotated.png where every single edge gets annotated with its own MTF50 value. The good-quality edges are annotated in Cyan, and then Yellow and Red annotations mean progressively worse edge quality (usually that's about edge orientation and edge length, lowkey).
  • -s, --surface — surface output mode. This one is on by default ✨ and it generates two output plots: a color-graded 2D view of the MTF50 values all across the image, plus a 3D surface plot of that exact same data. Two plots, one vibe.
  • -p, --profile — profile output mode. Enables Profile mode, and mtf_mapper produces a plot called profile_image.png showing a side-view of the MTF50 values. The whole point of this mode is figuring out whether a camera is front-focusing or back-focusing. Heads up: you need a special test chart generated with mtf_generate_test_chart for this mode to work correctly 🫶
  • -r, --raw — raw output mode: it just dumps the MTF50 values into a file called raw_mtf_values.txt.
NB: the -q output option also produces files containing the MTF50 values, but every entry of that output also gives you the image coordinates of the measurement. Just so you know. 👑
  • -e, --esf — produces edge spread function (ESF) outputs. Every edge corresponds to one row in an output file called raw_esf_values.txt. Each row contains 256 samples, and those correspond to a window of 32 pixels centered on the edge, oversampled by a factor of 8 — so consecutive samples are 1/8 pixel apart. Fair warning: there is currently no simple way to identify which edge in the input image ends up in a particular row 😭 If your input image contains a single square, then honestly just pick any row, bestie.
  • -f, --sfr — produces spatial frequency response (SFR) curve outputs. Each edge corresponds to one row in an output file called raw_sfr_values.txt. Each row starts with the edge orientation (in degrees), followed by 64 values corresponding to the contrast measured at a frequency resolution of 1/64 cycles per pixel. In other words, those 64 values span the frequency range [0,1) cycles per pixel. See -e for advice on matching rows to edges 🦋

By default this is an SFR curve, meaning the DC component is always normalized to 1.0. See the --absolute-sfr switch if you want true MTF curves.

NB: the -q output option also produces files containing the SFR curve, but each entry of that output also provides the image coordinates of the measurement. ✨
  • --absolute-sfr — do not normalize the SFR curve, i.e., the DC component is not normalized to 1.0. This is useful when you're evaluating the MTF response of algorithms that may reduce overall edge contrast. Very niche, very valid.
  • --nosmoothing — disables SFR curve (MTF) smoothing. By default MTF Mapper applies Savitzky-Golay filters to the SFR curve to improve its appearance. The only known disadvantage of this smoothing is that the sharp valley surrounding the first zero of the SFR (if present) can be over-smoothed — and in that case the --nosmoothing option is recommended 💯
  • -q, --edges — a better choice than either -r or -f, fr fr. This option produces two output files called edge_mtf_values.txt and edge_sfr_values.txt, and both of them combine edge location with the MTF measurement. Iconic behavior.

Each row of the edge_mtf_values.txt file contains six space-separated columns: block_id edge_x edge_y mtf50 corner_x corner_y. The block_id can safely be ignored (it depends on the order in which target squares were processed). The pair (edge_x, edge_y) denotes the pixel coordinates of the centroid of the edge, and mtf50 is the MTF50 value in cycles per pixel (that's the default), or in lp/mm if the --pixelsize option was specified. Lastly, the pair (corner_x, corner_y) denotes the pixel coordinates of the corner of the target (black square) associated with this edge, and can be safely ignored.

The format of the edge_sfr_values.txt file is similar: each row starts with five columns: block_id edge_x edge_y edge_angle radial_angle, followed by 64 more floating point values denoting the SFR. The edge_angle column denotes the orientation of the edge relative to the image rows/columns, modulo 45 degrees. This angle should preferably be at least 2 degrees but less than 44 degrees for best results. The fifth column, radial_angle, is just the angle of the radial line from the image centre to the edge centroid — so you can use it to work out whether an edge is in a Sagittal or Meridional orientation with respect to the image centre, which is assumed to be centered on the test chart. 🌈

The SFR part (those last 64 values on each line of edge_sfr_values.txt) represents the contrast values of the SFR (or MTF, if you prefer) sampled at spatial frequencies of i/64 cycles per pixel for i from 0 to 63 inclusive.

If you use the --full-sfr option together with -q, the SFR component of each line of edge_sfr_values.txt will comprise 128 values (rather than 64), and the corresponding spatial frequencies are i/64 cycles per pixel for i from 0 to 127 inclusive.

NB: the only reliable, safe way to compare the output of MTF Mapper between different images captured using the same camera (say, an f/2.8 vs an f/4 image capture) is to use the pixel coordinates (edge_x, edge_y) of a measurement from image A to find the closest corresponding measurement from image B — assuming you don't move the camera around too much, or rotate the chart or something like that (and in that case you can use the Monkres assignment algorithm to calculate the correct pairing). Please do not rely on the order of the rows of the edge_mtf_values.txt and edge_sfr_values.txt files. I am begging you. 😭
  • --full-sfr — outputs the full SFR/MTF curve (up to 2 c/p) when combined with -q or -f. The default is to only output the curve up to 1 c/p. Relatively few cameras have meaningful contrast after 1 c/p, so take note that noise tends to dominate the MTF curve out there 💀
  • --lensprofile — this output option produces a Meridional / Sagittal MTF chart similar to those published by lens manufacturers. It requires a lensgrid type MTF Mapper test chart image (but it'll work with older grid style charts too, no cap). The resulting output lensprofile.png is a plot of contrast vs radial distance from the centre of the image, at three specified spatial resolutions (see --lp1, --lp2, --lp3). It's recommended that you use the --pixelsize option together with --lensprofile so that the units of the chart are in mm for the x-axis, and so that the spatial resolutions are in lp/mm — otherwise the x-axis units are pixels and the spatial resolutions are in c/p, which is not a common choice for this type of chart. Just saying. 🧚
  • --chart-orientation — visualizes chart orientation relative to the camera to assist in aligning the camera perpendicular to the chart. This option requires that the input image contains circular fiducial markers (e.g., focus and lensgrid MTF Mapper chart types), and produces an output file called chart_orientation.png which graphically illustrates the yaw/pitch/roll angles of the test chart relative to the camera. The objective here is to iteratively adjust the chart orientation to bring the yaw and pitch angles as close to zero as possible — preferably below 0.5 degrees — to ensure that the camera's optical axis is perpendicular to the test chart. Once the alignment is satisfactory, other outputs (e.g., -a, or --lensprofile) can be derived from subsequent images of a lensgrid style chart. For this option to work, the correct lens focal ratio must be specified (see --focal-ratio). 🎯
  • --focal-ratio ratio — specify the focal ratio for use in chart orientation estimation. The focal ratio is computed as focal_length / sensor_width, e.g., 50 mm / 23.6 mm when using a 50 mm lens on an APS-C sized DSLR. This option is only needed if you combine it with the --chart-orientation option.
  • --lp1 resolution, --lp2 resolution, --lp3 resolution — specify the three spatial resolutions to use when plotting a --lensprofile. Three resolutions, three flags, one gorgeous chart 💖
  • --focus — this output type produces a visualization of the peak focus location. A special MTF Mapper chart type is required (focus), which should be imaged at a 45-degree tilt with respect to the camera. This chart is not suitable for use with camera autofocus; rather, it's intended to calibrate a manual focus lens, or to measure focus shift in a lens. Please see the MTF Mapper user guide for more information.
NB: note that the --focus output option is incompatible with most other output options (e.g., -a, -s, --lensgrid, -q, etc.), so do not use this option unless you are sure you want to. Like, sure sure. 🙈
  • --mfprofile — this output type produces a visualization of the curve formed by the intersection of the "surface of best focus" and the test chart. A special MTF Mapper chart type is required (mfperspective), which should be imaged at a 45-degree tilt with respect to the camera. This chart is intended for manual focus operation since the chart does not contain suitable central features for autofocus operation.
NB: note that the --mfprofile output option is incompatible with most other output options (e.g., -a, -s, --lensgrid, -q, etc.), so do not use this option unless you are sure you want to. Same energy as above, bestie. 🫶

ok so this whole section is about the fact that lenses are, like, dramatic and bend light in ways that are not a vibe. read on bestie 💅

  • --esf-sampler line | quadratic | piecewise-quadratic | deferred — picks which approximation models the curve of your image edges. the default is piecewise-quadratic, okay? now listen:
    • if your image has absolutely no radial lens distortion, then line is optimal. like, that's her moment.
    • quadratic and piecewise-quadratic do exactly what their names say (iconic of them): the straight edges of the target objects on the test chart — which we're assuming are straight — get modelled with a (piecewise-) quadratic curve.
    • deferred is a special girl: she's only available when you've specified an overall lens distortion model using --equiangular, --stereographic, or --optimize-distortion. and heads up 🫶 selecting any one of those options automatically forces --esf-sampler=deferred.
  • --stereographic focal length(mm) — treat the input image as a stereographic mapping (fisheye, bestie 🐟) with the focal length you give, in mm. with this option, the annotated output image (that's output option -a) will be unmapped, i.e. in its rectilinear equivalent mapping — but the MTF measurements are still made in the original (distorted) image. also: this option requires a pixel pitch to be specified using the --pixelsize option. no pixelsize, no party.
  • --equiangular focal length(mm) — same energy, different mapping: treat input image as an equi-angular mapping (fisheye) with the specified focal length in mm. with this one too, the annotated output image (output option -a) will be unmapped, i.e. in its rectilinear equivalent mapping, but MTF measurements are still made in the original (distorted) image. and yep, this option also requires a pixel pitch specified using the --pixelsize option. 💖
  • --optimize-distortion — this one's a whole two-step process to compensate for radial lens distortion:
    1. a two-parameter division model gets fitted, so you get a distortion model of the lens
    2. then MTF measurements happen in the original (distorted) image, but using the undistorted image to guide the process

the annotated output image (output option -a) is based on the undistorted image. this option works best when the test chart — preferrably the lensgrid chart — fills the frame, and the average edge length is 200 pixels or more. she likes a full frame, what can I say 👑

note that this option can, in practice, replace the use of the --stereographic and --equiangular undistortion methods.

also note: it is not necessary to undistort the image (to produce straight target edges) to obtain accurate MTF measurements. by default, MTF Mapper now uses a piecewise-quadratic curve to model target edges, so those three undistortion methods (--stereographic, --equiangular, and --optimize-distortion) are mostly for research purposes now. sorry to the researchers, ilysm 🧚

  • --no-undistort-crop — by default, MTF Mapper estimates which part of the undistorted image is actually usable, i.e. not stretched too much, and crops the output accordingly. this option overrides that cropping when used with the --equiangular and --stereographic options.
⚠️ this can produce very large output images, so use with care. like, your disk said please 😭

👯 SEE ALSO 👯

the besties, the girlies, the whole friend group:

  • mtf_generate_rectangle
  • mtf_generate_test_chart
  • mtf_mapper_gui

🫶 AUTHOR 🫶

Frans van den Bergh <fvdbergh@gmail.com> — Author.

and that's the whole page, bestie!! 💖 you just read the full MTF_MAPPER(1) manual — from this release, dated 05/09/2026 — and honestly? slay. go measure some MTF, you absolute icon 🎀✨🌸

📦 where this page comes from