PTShift  Instructions  

PTShift version 1.8 beta 6 (July 2007)
By Eric Gerds


Many people have found the PanoTools Radial Shift filter to be very useful for removing or reducing transverse Chromatic Aberration (tCA) from camera images. To use this filter, a set of polynomial coefficients (a,b,c,d) for each of the 3 color channels must be supplied by the user. If the abcd coefficients are well chosen, then the filter will do a good job in removing tCA from your images. If your coefficients are poorly chosen, then obviously your results will not be satisfactory. [The Radial Shift filter should be found within the PanoTools Photoshop Plugin called 'Correct', or a name similar to that.]

So how does one get good abcd values? You can use trial and error, but that is cumbersome and may not be very precise.

Therefore a couple of techniques have been proposed by Jim Watters and Erik Krause to calculate the abcd parameters. Based on the ideas of Watters and Krause, PTShift was developed.

PTShift is a Photoshop CS/CS2/CS3 script will help the user to determine the PanoTools Radial Shift parameters (a,b,c,d) needed to reduce the tCA in your images. Each time you run PTShift, it will require you to SHIFT a color channel (Red, Green, or Blue) at a control point x,y so that the tCA is no longer visible at that control point. This shift data is used by PTShift to calculate the abcd values for your camera lens.

Once you have your abcd values, you can load them into the PanoTools Correction plugin in Photoshop, and run it on your images to correct CA.

 Requirements For Using PTShift 

The user must have PanoTools and the PanoTools Photoshop plugins installed on their computer to use PTShift. We assume here that the reader already has some familiarity with PanoTools and the PanoTools Photoshop plugins.

You can get the old (ie. original) PanoTools and PanoTools plugins here. The updated 16 bit version of PanoTools and PanoTools Photoshop plugins is here.

PTShift works with either the old PanoTools Photoshop plugin Correct.8BF, or with the newer PanoTools Photoshop plugin PTCorrect.8BF. You can have either one of these (or both) installed in Photoshop.

PTShift only works with Windows & Photoshop CS/CS2/CS3. It will NOT work for any previous versions of Photoshop (7 or lower).

PTShift will no longer be compatible with Macintosh.

 Correcting CA Without PTShift Or The PanoTools Radial Shift Filter 

You don't absolutely need PTShift or the PanoTools Correction filter to deal with tCA. If you prefer an EASIER method, you could just use the built in capabilities of Photoshop CS/CS2, or even PTLens. These will allow you to easily correct linear or almost linear tCA (meaning that the amount of tCA increases linearly with distance from the image center).

Photoshop CS includes the Adobe Raw Converter, which allows you to correct tCA for RAW images. And Photoshop CS2 has the added ability to correct tCA for non-RAW images.

However, if you wish to have the ability to remove both linear AND non-linear tCA, then using PTShift along with the PanoTools Correction plugin would be an option. The drawback is that there is a learning curve when trying to master PTShift.

 Installation Instructions For PTShift 

PTShift really has 2 parts: The Javascript itself ("PTShift.js"), and an Action Set (called "PTShift Actions.atn") which interacts with the script.

1) Load the "PTShift Actions.atn" action set into the Photoshop Actions palette. It is very important that you DO NOT change the name of this action set, because the Javascript will call the actions in that action set, and it expects an action set with that exact name. DO NOT change the names of any of the actions within this action set either.
[Note: For Photoshop CS2, PTShift will automatically set the Playback Options of the Actions palette to 'Step by Step'. This is done so that PTShift will work properly with CS2.]

2) Then place the "PTShift.js" Javascript somewhere you prefer on your hard drive. You have 2 basic choices how you want to call this script from within Photoshop:

2a) Create a Photoshop action in the Actions Palette that will call the "PTShift.js" Javascript. Make sure that this Photoshop action has a KEYBOARD SHORTCUT (such as a Function Key) associated with it, to make it easy to run the script.


2b) If you cannot create a keyboard shortcut to run the Javascript, then simply copy the "PTShift.js" Javascript into
the \Presets\Scripts folder in the Photoshop directory, so that our Javascript will show up in the Photoshop menu : File -> Scripts.

3) Don't forget, you will also need to make sure that you have PanoTools installed on your computer.

 Running PTShift For The Very First Time 

When running PTShift for the very first time, it is recommended that you enter the PREFERENCES panel (press the "PREF" button). In there, you can set your user preferences.

For now, you should make sure the "IMAGE BASELINE ABCD" checkbox in the Preferences panel is unchecked. The reason for this is that for now we are only interested in correcting tCA. (You would only CHECK this checkbox if you wanted to correct barrel/pincushion distortion and tCA at the same time. But lets not complicate things right now).

A reasonable value for the radius of the control point boxes is 25. PTShift will draw a box around a location x,y whenever you save a control point at that x,y.

 How To Use PTShift On An Image With TCA 

1) Load an image that exibits tCA into Photoshop. This image should have one image layer with 3 color channels (Red, Green, Blue). The image should be on the Background layer of the document. Note: PTShift will eventually add additional layers to your document.

Make sure you are in RGB mode, NOT CMYK or LAB.

2) Now you need to choose a control point x,y in your image where you would like to correct the tCA (chromatic aberration). Using the Photoshop RECTANGULAR MARQUEE TOOL, draw a selection box of any size around a location that exhibits CA. The actual x,y control point, as far as PTShift is concerned, will be the exact center of this selection box. The box can be as small or as large as you want. It is practical to use maybe a 30 pixel x 30 pixel box, but the exact size is not important.

3) Now you should run PTShift.

  To speed up the execution, PTShift will prefer to work on 8 bit images (instead of 16 bit). If you run PTShift on a 16 bit image, it will automatically convert the image to 8 bits. (This does not mean that you won't be able to run the PanoTools Correction plugin on 16 bit images, assuming your filter has that ability. Converting to 8 bits is ONLY a trick that PTShift uses, and has absolutely no ill effect on the final results.)

  Also, the x,y location of the center of your selection box will be displayed. An x,y of 0,0 would correspond to the upper left corner of your image. R is the distance in pixels of x,y from the image center, and dR is the amount that a channel has been shifted at x,y.

4) Select one or more of the RGB checkboxes to choose which color channels (Red, Green, or Blue) that you wish to shift.
   For the Sigma 8mm fisheye lens, for example, this would be the Red channel. The Red channel would need to be either radially expanded or contracted so that it properly aligns with the Green and Blue channels.

5) For the time being, you may leave the "PANOTOOLS CORRECTED IMAGE" checkbox unchecked if you wish.

6) Using the 4 shift buttons <<,  <,  >  or  >>  specify a dR[User] channel shift to remove the tCA inside the rectangular selection box. The  <<  and  <  buttons will shift the channel towards the center of the image, causing dR[User] to decrease. The  >  and  >>  buttons will shift the channel away from the center of the image, causing dR[User] to increase.
  You will notice that most times when you press the  <  or  >  buttons (which change dR[User] by 0.1 pixels), that the channel does not appear to shift. The reason for this is that PTShift can only visually shift a channel in ~1 pixel increments when the PanoTools Corrected Image checkbox is unchecked.
  Do not be concerned by this. At this point all you want to do is make a reasonable guess for the value of dR[User]. If you adjust your dR[User] to 0.4 pixels, for example, you will notice that nothing inside the selection box has shifted at all. But if you now choose a dR[User] of 1.2, then you will definitely see a shift. Suppose we decided that dR[User]=1.2 was too big a value, and we choose instead to go with dR[User]=0.5 pixels.
  This dR=0.5 is almost certainly not an accurate value needed to precisely remove the tCA in the selection box, but at this point it does not matter.

7) Press "SAVE dR" in the main dialog window when you are satisfied with your guess for the value of dR[User]. A colored box will be drawn by PTShift around the x,y control point that you have saved. If the active color channel in PTShift is red, then the drawn box will be red.

8) You can now get an accurate preview of how well your chosen dR[User] removes tCA inside your selection box. Select the 'PanoTools Corrected Image' checkbox. PTShift will cause the PanoTools Correction filter to run on your image using the dR[User] value you have chosen. [Windows users note: the very first time in a Photoshop session that you select this checkbox, the PanoTools Correction gui may pop up. Simply press OK and it will run.]
  After the PanoTools filter has completed running, you may want to press the "TOGGLE dR" button a few times. This button will allow you to compare the image before correction (ie. dR = 0) to the image after correction (dR = 0.5, or whatever value you originally chose).
   You will notice that the dR[PT] field now also displays a value. dR[PT] is the dR value calculated by PTShift, and is the amount of shift you are actually getting when you view the PanoTools Corrected Image - as opposed to the amount of shift you wanted to get with dR[User].
   dR[PT] and dR[User] will not always necessarily be the same. When you have multiple control points at different x,y locations, PTShift will try to calculate the best fit curve that satisfies all the dR[User] values at all the control points. The dR[PT] values are the result of this best fit calculation.
   PTShift tries to find the 4 parameters a,b,c,d to satisfy the PanoTools Radial Shift equation (a 4th order polynomial equation). If you specify 4 or fewer control points, then dR[PT] and dR[User] will be exactly the same at all points. If you specify 5 or more control points, then dR[PT] and dR[User] will probably be slightly different for some of the points.

9) The PanoTools Corrected Image will most likely make you conclude that your dR=0.5 value does not shift the channel enough, or that it shifts the channel too much. Let us suppose that it does not shift the channel enough.
  To remedy this, you may leave the "PANOTOOLS CORRECTED IMAGE" checkbox selected if you wish. Use the 4 channel shift buttons to change the dR[User] to a better value, say dR = 0.7. Press the 'Save dR' button again. The PanoTools Correction plugin will automatically rerun on your image using your updated value of dR[User].
  You can adjust the value of dR[User] in this manner as often as needed until the tCA in the selection box is removed completely.

10) If you wish to enter another control point at another x,y location in your image, then go to STEP 5 above. You may place as many or as few control points as you wish. I recommend you have at least several control points distributed at different distances R from the image center. This will ensure that the tCA is removed throughout the entire image.

11) When you feel you have enough control points, then ...

Windows Users: Assuming you have used the "PANOTOOLS CORRECTED IMAGE" checkbox, then you can simply exit PTShift. Your calculated abcd values are already stored in the PanoTools Correction plugin - just start the plugin and look at the Radial Shift filter to verify this.
   As an alternative, while PTShift is running you could just press the "SAVE ABCD" button. PTShift will save the abcd values for all 3 color channels into a file that can be loaded into the PanoTools Correction plugin for the purpose of removing tCA.

 How to Edit a Control Point in PTShift 

Let us suppose you have a saved control point located at x,y in your image with a channel shift of dR[User]=1.2 for the red channel. We assume here that PTShift is not running at the moment, and for whatever reason, you decide that the x,y control point needs to have a different dR, say dR[User]=1.3.

1)  Using the Photoshop RECTANGULAR MARQUEE TOOL, draw a box around the control point x,y. Now start PTShift.

2) PTShift will lock onto that control point x,y and will display the channel shift dR[User] for any color channels at that point. If the "PANOTOOLS CORRECTED IMAGE" checkbox is selected, then the dR[PT] values will also be displayed.

3) Then use the  <<,  <,  >,  or  >>  buttons to change the channel shift dR[User] to 1.3 (or whatever value you wish).

4) When you have the dR value you like, press the "SAVE dR" button to save the control point. An alert box will pop up asking if you wish to replace the control point. Answer YES. You have now successfully edited your control point.

 Using PTShift With Custom Baseline abcd For Your Image 

PTShift accepts a custom baseline a,b,c,d value in the Preferences dialog window.
(If you choose not to use any custom baseline, then uncheck the 'Image Baseline' checkbox - in this case the default values of abcd = 0 0 0 1 are used)

The use for this option is so PTShift can calculate a single set of abcd values (for Red, Green, Blue channels) that corrects both lens distortion (barrel or pincushion) and transverse Chromatic Aberration simultaneously.

To use this feature :

A) Let us suppose we start with an image that exhibits both distortion (barrel/pincushion) and tCA.

B) Use PTShift as previously described to remove the tCA only in your image. By this we mean that the "BASELINE ABCD" checkbox (in the PREFERENCES window) is deselected while you enter your control points to remove the tCA. We completely ignore any barrel/pincushion distortion at this time.

C) When you are completely satisfied that you have removed the tCA from your image, you should then determine the abcd parameters that will correct the lens distortion (Barrel/Pincushion) for your image. You can determine the distortion using PTGui or by some other means.

Also, remember that these abcd parameters will follow the equation d = 1 - a - b - c.

D) Enter the abcd values from step C) into the "BASELINE ABCD" area in the PREFERENCES dialog window. Make sure the checkbox for Image Baseline is checked when you enter the values. These abcd values will remove the lens distortion from your image.

You only have to enter the a,b,and c values. The 'd' value is automatically calculated for you. using d = 1 - a - b - c after you press the "SAVE" button in the PREFERENCES window.

[Note: Baseline values of abcd, the PanoTools radial equation

rs = a(rd^4)+b(rd^3)+c(rd^2)+ d(rd)

will only have valid solutions within a limited radius RMAX from the image center. Sometimes, this RMAX can be sufficiently small that some of your control points x,y will lie outside the circle of radius RMAX. If this occurs, those outermost control points will be ignored when PTShift calculates it's abcd values.

The PREFERENCES Dialog Window will give a warning message if this should occur for the abcd baseline you have chosen.]

E) Press the "SAVE" button in the PREFERENCES window.

F1) If you wish, you may select the "PANOTOOLS CORRECTED IMAGE" checkbox. The PanoTools Correction plugin will run, and now both the lens distortion and tCA should be simultanously corrected. The advantage here is that a single set of abcd values are being used, and hence only one interpolation is being performed on your image to remove 2 separate problems: distortion and tCA.

F2) On the other hand, you may just choose to press the "SAVE ABCD" button to save the final abcd parameters into a file.

 ABCDparams and ABCDparams(NoFringes) 

PTShift will create 2 different output files when the "SAVE ABCD" button is pressed. These 2 files are named ABCDparams and ABCDparams(NoFringes).

When you are ready to apply one of these files to an image (by loading it into the PanoTools Correction plugin), which file should one use? You will almost always want to use the ABCDparams file.

When you load the ABCDparams file into your PanoTools Correct plugin and apply this to an image, 2 things happen:

1) The anchor channel(s) in that image have the Baseline abcd applied to them.

2) The shifted channels will line up with the anchor channel(s), and thus the tCA will be removed from the image.

[Reminder: Shifted channels are those that you shifted in PTShift to remove tCA. Anchor channels are those channels that you did NOT shift in PTShift. Baseline abcd are values supplied by the user to remove barrel/pincushion lens distortion.].

When you load the ABCDparams(NOFRINGES) file into your PanoTools Correct plugin and apply this to an image, 3 things happen:

1) The anchor channel(s) have the baseline abcd applied to them

2) The shifted channels are transformed so they line up with the anchor channel(s).

3) Then, all 3 color channels are scaled radially outwards by the same amount until there are no fringes* at the edges/corners of the image. [Fringes* at the image edges can be created by steps 1) and 2) if any channels are radially shifted inwards.]

The implication of step 3) is that the final abcd applied to the anchor channels is NOT exactly the baseline abcd you specified.

So, if you absolutely need the anchor channel(s) to have the baseline abcd applied to them precisely as specified in PREFERENCES, then you should use the ABCDparams file only. If there are any fringes at the outer edges of the image, then you may just have to crop the resulting image.

In most cases, I would just recommend applying the ABCDparams file to your images.


- The control points you choose should be distributed at different radial distances from the input image center. If you choose all your control points to be at nearly the same radial distance from the center, even if you choose many points, then your Transverse Chromatic Aberration (tCA) correction results will be quite bad. It is best to have your control points distributed from the very image edge/corners to the near center. Though, you do not have to place them too close to the center since there should be no tCA there.

- If your control points are properly spread at different radial distances, then it is not really necessary to use a large number of control points. You could probably get away with using only 4, 5, or 6 control points for a given color channel. The reason for this is that PTShift allows you to specify dR[User] values in 0.1 pixel increments, so you can always 'tweak' the dR value at each control point by very small amounts until you get the exact abcd value you need.

- You are permitted to specify shift dR[User] = 0 at a control point x,y. This is perfectly valid, assuming of course that the channel itself does not NEED to be shifted at that x,y (ie. there appears to be little or no CA at x,y in the first place). This will occur near the image center, though for some lenses it may occur elsewhere as well.

- When you find the abcd parameters for an image that was taken at a certain focal length/focus distance, it may be best to apply the abcd tCA correction on other images taken with the same focal length/focus distance.
So, you would most likely have to get a new set of abcd parameters if you want to correct tCA in images taken at different focal lengths, different focus distances, with different lenses, etc...

- Note that the data files that PTShift creates are stored in the same folder as your input image. It is therefore perfectly valid to use more than one input image to determine the abcd values. Just make sure that the input images are all in the SAME FOLDER, and that they all were taken with the same focal length/focus distance, and so on.
So, if you have input images A, B, and C in the same folder, you could run PTShift on Image A, then you could run it on image B, and then on Image C - to give you the abcd values.
The trick to remember is that when you load Image B into Photoshop and run PTShift, then just press the "SHOW BOXES" button to show you all the control points that you created in Image A. When you load Image C and run PTShift on it, press "SHOW BOXES" to show all the control points you created from Images A and B, and so on.

Using multiple input images may sometimes be necessary in case you do not have enough features distributed throughout any one picture to specify the channel shift.