3. Usage

3.1. Resources

• A peer-reviewed paper describing the methods developed and implemented for Discorpy is available on Journal of Synchrotron Radiation.

• 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. When overlaying reference points on a calibration image using Matplotlib, be aware of this difference.

The coordinates of reference points extracted from a calibration image refer to the image coordinate system (top-left origin). The values for the center of distortion are also referenced from this origin.

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