3. Usage

3.1. Resources

• A technical report explaining step-by-step on how to calculate distortion coefficients from a dot pattern image is available at Zenodo.

• Examples of how to use the package are in the “/examples” folder at the github page.

• Coefficients determined by the package can be used by other tomographic software such as Tomopy, Savu, or Algotom for correction.

3.2. Notes related to Python programming

In the workflow of calibrating a distortion target, some functions work with Python lists, some with Numpy arrays. They are different objects and can cause confusion or give rise to errors if users don’t use these objects properly. There are many tutorials online to explain the difference between them. Here we only show some examples related to how they may be used with Discorpy.

• Initialization:

  import numpy as np
  
  # Declare a Python list
  points_n1 = [[0.0, 0.0], [0.0, 0.0], [0.0, 0.0]]
  # Declare a Numpy array
  points_n2 = np.asarray(points_n1, dtype=np.float32)
  # or
  points_n2 = np.zeros((3,2), dtype=np.float32)
  

• Indexing:

  # For a Python list
  element1 = points_n1[0][1]
  # For a Numpy array
  element2 = points_n2[0,1]
  
  # For a Python list
  sub_set1 = points_n1[0][0:2]
  # For a Numpy array
  sub_set2 = points_n2[0,0:2]
  

• Math operations:

  # For a Python list
  points_m1 = points_n1 + 1.0 # >> Raise an error
  # For a Numpy array
  points_m2 = points_n2 + 1.0 # >> Add 1.0 to every element of the array.
  

• Storing:

  # A Python list can store different objects with different size.
  points_n1 =([[[0.0, 1.0], [1.0, 2.0]], np.ones((3,2))])
  # A Numpy array can only store Numpy objects with the same size.
  points_n2 = np.asarray(([[[0.0, 1.0], [1.0, 2.0]], np.ones((2,2))]))
  

In Discorpy, Python lists are mainly used to store Numpy arrays with different size. For example, in the grouping step, the number of extracted reference-points on each line are not the same.

It is important to be aware that different methods may use different coordinate systems. In the image coordinate system, the origin is at the top-left corner of the image. For example, the center-of-mass of an object refers to this origin. In the plotting coordinate system, the origin is at the bottom-left. The parabolic fits of horizontal lines refers to the bottom-left origin, however the one of vertical lines refers to the top-left origin with coordinates swapped. This is necessary to avoid the numerical problem of fitting lines nearly perpendicular to the axis.

3.3. Demonstrations

• 3.3.1. Process a high-quality calibration image
• 3.3.2. Process an X-ray target image having perspective effect
• 3.3.3. Process a challenging X-ray target image
• 3.3.4. Process a line-pattern image
• 3.3.5. Correct both radial distortion and perspective distortion
• 3.3.6. Calibrate a camera using a chessboard image
• 3.3.7. Correct perspective distortion
• 3.3.8. Correct radial distortion of an image without using a calibration target
• 3.3.9. Useful tips