A graphical user interface tool for shape analysis using Elliptic Fourier Descriptors (EFD).
A user-friendly software designed to offer improved contour extraction, efficient EFDs calculation, and complete EFD normalization across all basic contour transformations.
Option 1. Install Conda (if not already installed): - Download Anaconda from the official website: https://www.anaconda.com/ - Follow the installation instructions for your operating system
Option 2. Install Python (if not using Conda): - Download Python 3.8 or later from the official website: https://www.python.org/downloads/ - Follow the installation instructions and ensure you select the option to add Python to your system PATH
- Open the Anaconda Prompt
- Create a Conda environment with Python 3.8:
conda create -n ElliShape python=3.8 - Activate the environment:
conda activate ElliShape - Install the ElliShape package:
pip install ElliShape - Download the required model weight files:
python path/to/download_pth.py - Run ElliShape:
ElliShape
- Open the Command Prompt
- Install the ElliShape package:
pip install ElliShape
- Download the required model weight files:
python path/to/download_pth.py
- Run ElliShape:
ElliShape
- Ensure your environment meets the Python version requirements.
- The model weight files are essential for running ElliShape. Make sure to download them before using the software.
- For detailed documentation and troubleshooting, refer to the official website or contact support.
The software comprises two components: contour extraction and elliptic Fourier analysis.
Contour extraction involves four steps: manual target selection, automatic segmentation, manual correction of automatic contour outlining, and automatic chain code generation. Various functions address challenges of contour extraction during specimen preservation and digitization, such as incomplete edges due to white strips, low image contrast, and noises from fragile, overlapping, and damaged organs.
Figure 1. Software interface.
Step 1: Image loading
Click the 'Folders' button and choose the folder containing your image files. All file names with extensions '.jpg', '.png', '.tif', and '.bmp' will be listed. Choose the desired image file to load it into the program (Fig. 2). Use the 'Next' and 'Previous' buttons to navigate through the loaded images.
The test images can be found in the 'ElliShape' folder you downloaded.
Figure 2. Image loading.
Step 2.1: Object selection
Users can zoom in and out using the mouse scroll wheel and navigate left and right by dragging the slider to quickly locate the object (Fig. 3). Object selection is facilitated through two methods: automated segmentation and manual polygon selection.
Figure 3. Object selection.
Method 1: Object selection via "automated segmentation"
After drawing a rectangular box around the object in the left window, click the 'automated segmentation' button. The segmented object will appear in the lower middle and right windows as a binary image (Fig.4), enabling direct chain code generation.
Figure 4. Object selection via "automated segmentation".
Method 2: Object selection via "Polygon Tool"
To select a region of interest (ROI), use the 'Polygon Tool' button. Left-click to create a polygon around the leaf, connecting points. Right-clicking to close the polygon and display the selected object in the upper middle picture window (Fig. 5). To begin a new selection, right-clicking to end the current one.
Figure 5. Object selection via "Polygon Tool".
Step 2.2: Color inverting
If the foreground objects exhibit high grayscale values and distinct contrast with the background, the 'Inverted Colors' function is necessary. However, if they do not, it should be utilized.
An illustration of an image featuring a black background is shown in Fig. 6.
Figure 6. Color inverting.
Step 2.2: Image enhancement and grayscale conversion
If the foreground objects lack noticeable contrast with the background, use this step, as shown in Fig. 7.
Note: Clicking the 'Image Enhancement' button multiple times will superimpose the enhanced effect. To revert to the original grayscale image, click the 'Grayscale Conversion' button.
(2) the image after using function
(1) the original image
Figure 7. Image enhancement.
Step 3: Chain code generation
Two methods are available for obtaining the object contour: 'Image Binarization' or 'Edge Detection', selectable via radio buttons (Fig. 8). 'Image Binarization' is the default method for contour extraction.
Figure 8. Two methods for obtaining the object contour.
Method 1: Contour extraction via "Image binarization"
Click the 'Binarization' button to convert the processed grayscale image into a binary image. The result will be displayed in the window below the middle section and in the enlarged view window on the right (Fig. 9).
To reduce noise in images with short chain code lengths (e.g. "the length is 2") , click the ' Erosion ' button (Fig. 10). Adjust the value in the box next to this button to control the size of the corrosion operation for desired results.
If the prompt indicates 'chain code is not close' and there are small gaps or holes in the target region hindering closed curve formation, click the 'Dilation' button to close the boundary (Fig. 11).
If the prompt indicates 'chain code is not close' and the editing window shows that a single pixel point causing interruption in the connecting line at the edge top, clicking the 'Corrosion' button or 'Dilation' button will close the boundary (Fig. 12). If your target object is broken, use the 'Editing' function in the right window. Zoom in using the mouse scroll wheel and pan the image, and draw white line to connect the broken parts by long-pressing the left mouse and dragging (Fig. 13). You can also use the left mouse button to draw a black line to break the connection, where the color of the line is the opposite of the background value. Right-click to pop up the "Reset" button to reset and undo all edits.
Notes:
(1) The more dilations performed, the greater the distortion of the object, so use an appropriate number.
(2) Zoom in until one pixel is clearly visible before editing the image to avoid positional deviations (Fig. 13).
(3) Decide whether to use corrosion, dilation, and editing functions based on the specific circumstances.
Figure 9. Binarization results.
Figure 10 Erosion operation. When the prompt words indicate the short length of chain code (e.g. "the length is 2"), click the ' Erosion ' button and obtain the corrected boundary.
Figure 11. Dilation operation. When the prompt indicates 'chain code is
not close' and there are small gaps or holes in the target region
hindering closed curve formation, click the 'Dilation' button to close
the boundary.
Figure 12. Dilation operation. When prompted that the 'chain code is
not closed' and the editing window shows a single pixel point
interrupting the connecting line at the top edge, clicking 'Dilation'
button will close the gap in the boundary.
Figure 13. Editing operation. When target object is broken, draw white
line to connect the broken parts by long-pressing the left mouse and
dragging.
Click the 'Chain Code' button to initiate chain code extraction, with a message box confirming its success (Fig. 14). The correctness and closure of the chain code are determined by its length and the presence of a red line in the middle right window. If the chain code is not closed, the break location is enlarged in the editing window for user edits, followed by clicking the 'Chain Code' button again until the result is correct.
Figure 14. Successful chain code extraction.
Method 2: Contour extraction via "Edge detection"
Various edge detection methods, including Canny, Sobel, Prewitt, and Roberts operators, as well as the log and zero-cross detectors, are available in the popup menu (Fig. 15). Select the desired method adjust the threshold using the slider. A lower threshold reveals more details, while a higher threshold detects fewer details. Optimal thresholding is achieved when clear edge contours are visible (Fig. 16).
In the editing window, users can connect disjointed contours and correct any contour errors (Fig. 17). Click the 'Chain Code' button to obtain the correct edge contour (green line) and chain code (red line) as shown in Fig. 18.
Figure 15. Edge detection method selection.
Figure 16. Threshold adjustment.
Figure 17. Contour connection.
Figure 18. Successful chain code extraction.
Step 4: Size calculation and saving
If a ruler is present, zoom in on the image in the left window to the ruler's location. Click the 'Click Two Points' button and select a starting point and an endpoint by left-clicking. The coordinates of the two points will be get. Enter the actual distance between the points in the right text box, for example, input '10' (Fig. 19). Choose the measurement units as 'mm' or 'inch'. If a ruler is absent, click the 'Skip' button. Provide a label for the object, then click the 'Save (Chain code, Labeled images, and size)' button to save the outputs with names appended with the user-defined tag. The files will be saved in the 'results' and 'label' directory located within the current program's runtime path. These outputs include:
Boundary coordinates: input file name_user-defined tag_b.txt
Chain code: input file name_user-defined tag_c.txt
Size: input file name_user-defined tag_info.xlsx, Sheet 1
Labeled images: input file name_user-defined tag.png
Figure 19. Size calculation.
Step 5: Ellipse Fourier Analysis page
Click the 'Elliptic Fourier Analysis' button to access a new page for obtaining normalized EFD data and visualizing reconstructed shapes (Fig. 20).
Use the 'Calculate and Save' button to save the EFD data. Users can input any integer as the number of harmonic coefficients, with the default value set at 35 (Fig.21).
Adjust the visualization number of the EFD, ensuring it is less than or equal to the maximum, by clicking the 'Plot Curve' button. The result is displayed in Fig. 22. Click the 'Save Curve' button to choose the path for saving the curve (Fig. 23).
Figure 20. EFA interface.
Figure 21. EFD calculation.
Figure 22. Curve reconstruction.
Figure 23. Curve saving.
Reference:
Kuhl, F. P. , & Giardina, C. R. . (1982). Elliptic fourier features of a closed contour. Computer Graphics & Image Processing, 18(3):236-258. https://doi.org/10.1016/0146-664X(82)90034-X.
Haines, A. J., & Crampton, J. S. (2000). Improvements to the method of Fourier shape analysis as applied in morphometric studies. Palaeontology, 43(4):765-783. https://doi.org/10.1111/1475-4983.00148.
Bonhomme, V., Picq, S., Gaucherel, C. and Claude, J. (2014). Momocs: Outline Analysis Using R. Journal of Statistical Software, 56(13):1--24. https://doi.org/10.18637/jss.v056.i13.
Wishkerman, A., & Hamilton, P. B. (2018). Shape outline extraction software (DiaOutline) for elliptic Fourier analysis application in morphometric studies. Applications in Plant Sciences, 6(12): e01204. https:// doi.org/10.1002/aps3.1204
Wu, H., Yang, J.-J., Wu, P., Li, C.-Q., Ran, J.-H., Peng, R.-H., & Wang, X.-Q. (2026). Complete elliptic Fourier descriptor normalization and its application in quantitative morphological analysis. Methods in Ecology and Evolution, 00, 1–12. https://doi.org/10.1111/2041-210x.70330