Solar Spicule Tracking Code (SSTC)version 1.0

User Manual

Developers:

Yuyang Yuan (SoMaS, ACSE), Gary Verth (SoMaS), Viktor Fedun (ACSE)

Plasma Dynamics Group, The University of Sheffield

January 2019

Contents

1 Introduction 1

2 Usage 12.1 Software environment setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.2 Description of the tool functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.3 Parameter setting and storage path of pre-processed and processed data . . . . . . . . . . . . . . . 1

2.3.1 Parameters and data path settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Example of solar spicules identification 4

4 Example of coronal loops identification 15

5 Release notes 18

6 Queries 18

7 Citation in the literature 19

The name of the main function of the code is devoted to KUUGA (Japanese Superman)

1 Introduction

Solar Spicule Tracking Code version 1.0 (SSTC v1.0, written in MatLab) is designed for automated detection,tracking and analysis of solar spicules properties (also applicable for coronal loop and other curvilinear featuresdetection in the solar atmosphere). The code works best with hi-resolution observational solar imaging data. Thechoice of either photospheric, chromospheric or coronal spectral lines depends on the particular features to beidentified and analysed. As an output, the code provides information on individual spicules/loops detected as wellas overall statistics. A gradient contour method is used to constrain identified spicule/loop boundaries as well astheir axis (the spicule/loop “spine”). Detection results may be influenced by quality of current observational data(DKIST data will be tested by the authors when available). The level of accuracy of the code can be improvedby adding more points along the spicule/loop “spine” (if the detection region has a particularity high density ofspicules/loops). This will also provide a more accurate time evolution of the spicules/loops. To improve robustness,Machine Learning (ML) will be implemented in the next version of the code. Data processing time of currentversion depends on user computing facilities (i.e. number of CPU cores, GPU performance) used.

2 Usage

This manual includes the following parts:

(1) software environment setting;(2) description of the tool functions;(3) setting of parameters and storage path to the (pre-) post-processed data;(4) examples of use.

2.1 Software environment setting

We recommend to use MatLab 2017a or later versions to avoid any incompatible conflicts with software.

2.2 Description of the tool functions

Apart from polygoem.m, arrow.m, arclength.m, all other functions were developed by Authors. Description andusage of these three functions can be found here: [1, 2, 3] (including copyright details).

2.3 Parameter setting and storage path of pre-processed and processed data

Before running SSTC, parameters and the data storage path have to be configured first.

1

Function name Description of functionKUUGA SSRU This is the main function which should be used to

process the sequence of images (video). Beforerunning it, parameters can be adjusted (tested) withKUUGA SSRU Image parameter test

KUUGA SSRU Image parameter test Similar to the main function (KUUGA SSRU)KUUGA SSRU Image parameter test has thesame structure but works with only one image (randomlytaken from the input video) for parameters testing or inputimage for coronal loop identification

image anl User should run image anl.m beforeKUUGA SSRU Image parameter test whenanalysing image data

Play H mov Visualise solar data (movie)Region select Select ”Region of interest” (ROI)SaveFrame Save frame of solar observation data (movie)image processing fun3 Frame processingimage processing fun3 2readHmovie Read solar observation moviesingle spicule Analysis of single spicule or coronal loop in the ROIsingle region of solar imagepolygeom fun 5point Spicule or coronal loop analysis. Use 5 points on spiculepolygeom fun 5point SC or coronal loop axis to construct the ”spicule or coronal

loop bone”polygeom fun 7point Spicule or coronal loop analysis. Use 7 points on spiculepolygeom fun 7point SC or coronal loop axis to construct the ”spicule or coronal

loop bone”polygeom fun 5point length Spicule analysis. Calculate the arc length of 5 points in the

”spicule bone(s)”polygeom fun 3point length Spicule analysis. Calculate the arc length of 3 points in the

”spicule bone(s)”polygeom Calculate centroid and moment [1]arrow Show arrow [2]arclength Calculate arclength [3]Average single length width Obtain oscillation, length, width of spicule or coronal loopAverage single length width one image

Table 1: Description of the tool functions

2

2.3.1 Parameters and data path settings

(a) Open the folder SSTC. You should see the full list of functions shown in the Table 1.(b) Search for the name of the main function KUUGA SSRU and open it. The main function has six parts andyou should set the parameters and path for the first part only. In the parameters part, create the folder for datastorage of pre- and post-processed frames. The parameters description is shown in Figure 1. An example of a Hαspicule movie, named halpha rbe.mov, is already provided in the folder (see Figure 2). The main function willautomatically analyse the example movie when the code is running. If you want to analyse another data set, makesure that this data is in the correct folder. The input video format could be .mov, .mp4, .mpg and other videoformats.

Figure 1: SSTC parameters setting.

3

Figure 2: Solar imaging data input setting.

The data processing time depends on the number of CPU cores used. The following two commands parpool andgpuDevice will improve the SSTC performance. Make sure that the number in the parentheses of the parpoolfunction is consistent with the number of CPU cores available. For example, when using 4 CPU cores the parpoolfunction should be set with parameter 4, i.e. parpool(4) before running SSTC.

3 Example of solar spicules identification

In this part, we will show you how to analyse data provided in the halpha rbe.mov file which is located in thefolder shown in Figure 1. Two sub folders are already created in the folder which are used for storing the originalframe (original frame sample folder) and post-processed frame (image process frame) data.

The overall procedure how to use the SSTC is:

Parameters adjustmentStep 1 KUUGA SSRU Image parameter testStep 2Step 3Step 4Step 5

Data processingStep 1 KUUGA SSRUStep 2Step 3Step 4Step 5

All these steps are described below.

Step 1: Open the main function

Parameters adjustmentThe KUUGA SSRU Image parameter test function will work only with one frame (randomly taken fromthe input video) to allow user to see the result of SSTC performance with chosen parameters (see Figure 1). It ispossible to repeat adjustment procedure i.e. Step 1 - Step 5 with a new set of parameters.

Data processingIf result is acceptable, copy parameters used for KUUGA SSRU Image parameter test into KUUGA SSRU.

4

Step 2: Click the run button of MatLab

SSTC will play the example solar movie (see Figure 3), then instructions will be shown in the command windows.The first instruction is shown in Figure 4a, which asks you if you want to compress the original video. By typingY/N, the quality of post process frame can be controlled. The quality of the video will not changed if you enter Nor n. The quality of initial data can be changed by choosing compression ratio in the range between 0 to 1. Makesure that this ratio is greater than 0 and no bigger than 1 (Figure 4b). It may be difficult to balance the processingtime available to achieve the required quality in the post processed frames. The processing time will be longest ifthe ratio is set 1.

Figure 3: Example of the input Hα imaging data.

Figure 4: Command window instructions. Left panel (a) asks if you want to compress the original video or processthe data with default quality. Right panel (b). The compression ratio is set in the command window.

Step 3: Select the region of interest (ROI)

After setting compression ratio, the video file will be separated into individual frames which will be stored inthe original frame sample folder folder. The next step would allow you to select a particular region ofinterest (ROI) within the entire frame. In current version, the ROI can be selected by using your mouse or touchpad as a rectangular area (shown in red) within frame (Figure 5). It is only within the selected ROI that the spiculeanalysis will be done.

5

Figure 5: Region of interest (ROI) marked as red rectangle. Left panel (a) shows original frame. Right panel (b)shows processed data after applying contrast stretch methods.

N.B. The pre-processing of the images strongly depends on PC or laptop performance. It also depends on thechosen compression ratio and the size of the ROI selected. The pre-processing time of the example movie tookbetween 10-13 hours (see laptop specification used for testing in Figure 6).

Figure 6: Laptop specification used for software testing.

Step 4: Spicule analysis

It is important to mention that at this stage SSTC has already identified most curvilinear features which can beidentified as likely spicules and features which are similar in shape but can be interpreted as unlikely spicules,e.g., they are too long (Figure 7). The recognised and categorised results are sensitive to the initial parametersettings. All identified curvilinear features are be stored in image process frame folder. Figure 8 showsanother ROI with a clear non-spicule feature which is shown with a black contour (this is the region where there isa sunspot).

(a) Categorising process (b) Likely spicules (c) Resulting ROI

Figure 7: Analysis of the ROI shown in Figure 5.(a) This shows the categorising process where blue indicates alikely spicule, red are impurities, and green are unlikely spicules. (b) Likely spicules are indexed with differentcolours. (c) The final post processing frame of the selected ROI showing only likely spicules with the backgroundremoved.

6

(a) ROI shown in red frame (b) Categorising process

Figure 8: Example of another ROI containing a sunspot.

Step 5: Visualisation of processed data

After processing of each frame, SSTC code categorises each polygon region as a spicule or non-spicule. Then ittraces spicules in the ROI from frame to frame. After that SSTC provides statistical results on the identified spiculesin the ROI and stores the results for further analysis. A multi-dimensional matrix is shown in Figure 9 providingstatistical information on each spicule. The 1st row shows the polygon region i.e. spicule location and the 2nd rowshows the start frame where the spicule was identified first time. In particular, in Figure 9, the 342nd spicule firstappeared at the 37th polygon region in the 18th frame. Then SSTC traces it in the 34th polygon region in the 19thframe and finally this spicule last appears in 29th polygon region of the 20th frame.

Figure 9: Spicule array example of No 341 and No342 spicule

After this step, in the command window you will be asked to enter a spicule index for further analysis. Oncethe index entered, SSTC will automatically provide parameters of requested spicule both in figures and commandwindows. This information includes: lifetime, changing of spicule width, length, transverse oscillation, etc. Thefollowing steps show how SSTC represents these statistical results.

Step 1: The command window will present the total number of spicules in ROI. For example, in Figure 10 4452spicules were identified in ROI. Then, SSTC will prompt you to input the index of particular spicule which shouldbe a number within index range. If the input index is 999, the system will automatically present all the informationcalculated for the 999th spicule.

7

Figure 10: Spicule analysis results

Step 2: Since SSTC defines the spicule boundary as a polygon, in the code we use the Unbiased Detector ofCurvilinear Structures method (UDM) method [4, 5] to calculate the unbiased centroid point of the curvilinearfeature profile to locate the start point of the tracing process. As an example the centroid point, also known asthe centre point, of the 999th polygon is shown in Figure 11. Additional to the centre point, 5 other points arealso calculated: edge point 1, centre point 2, centre point 1, centre point 3 and edge point 2. All these pointsare shown as red circles (see Figure 11). The magenta dotted line shows the main centroid moments. Only themain centroid moments in the 1st frame of spicule are used as the y-axis (spicule axis) of the new coordinatesystem that records the movement of 5 specific points. This new coordinate system has its origin at the centrepoint 1 in the 1st frame, and the positive direction of y-axis in this frame is from the origin towards the blackbold circle in the 1st frame. Other points calculated in a similar way. See e.g., the 7 axial points shown in Fig-ure 12. More points will provide better accuracy in calculation of spicule length. However, this will requiremore calculation time. In SSTC version 1, the 7 point method is already included. To use 7 axial points changethe name of function polygeom fun 5point to polygeom fun 7point in the single spicule func-tion. This is also applicable for coronal loop analysis by using 7 axial points e.g. change the name of functionpolygeom fun 5point SC to polygeom fun 7point SC in the single region function.

8

(a) 1st frame of 999th spicule (b) 2nd frame of 999th spicule

(c) 3rd frame of 999th spicule (d) 4th frame of 999th spicule

(e) 5th frame of 999th spicule (f) 6th frame of 999th spicule

Figure 11: 999th spicule with 5 specific points

9

Figure 12: 5th frame of 999th spicule with 7 axial points

The second set of figures (Figure 13) shows the moving trajectory of 5 axial points relative to the reference frame.Besides these figures, the command windows will also present the exact displacement of this trajectories in contrastto the reference frame (Figure 14). To calculate the spicule length (e.g., the arc-length of the spicule “spine” whichis shown as a black dotted line in Figure 11) 7 axial points are used (only 5 are actually shown on the defaultoutput images). Since most of them are unbiased points, the length and width of spicule can be regarded as beinga reasonable approximation to the actual length and width. This accuracy can be improved by using more axialpoints but is not implemented in the code yet. Similar to the length estimation, the width of a single spicule, orcluster of spicules (if the code cannot distinguish one spicule from another in a very high density region), is also beobtained. Lastly, when the reference frame of the spicule has been defined, its transverse oscillation are determinedby comparing the 1st central moment (e.g. spicule axis of the first frame) with consecutive central moments ofthe same spicule. The length, width and transverse oscillations of the 999th spicule are shown in Figure 16. Thelifetime of 999th spicule is shown in Figure 15 (i.e. this spicule was present in 6 frames). The x-axis shows that999th spicule exists from 56th till 61st frame. Finally, this spicule can be seen in Figure 17 frame by frame.

10

(a) Moving trajectory of center 1 (b) Moving trajectory of center 2

(c) Moving trajectory of center 3 (d) Moving trajectory of edge point 1

(e) Moving trajectory of edge point 2

Figure 13: Moving trajectory of 5 specific points of the 999th spicule.

11

(a) Moving trajectory of center 1 (b) Moving trajectory of center 2

(c) Moving trajectory of center 3 (d) Moving trajectory of edge point 1

(e) Moving trajectory of edge point 2

Figure 14: Displacement of 5 specific points of 999th spicule.

Figure 15: life time of 999th spicule

12

(a) Length change of the 999th spicule

(b) Width change of the 999th spicule

(c) Transverse oscillations of the 999th spicule

Figure 16: Length change, width change and transverse oscillations of the 999th spicule.

13

(a) 1st frame of the 999th spicule (b) 2nd frame of the 999th spicule

(c) 3rd frame of the 999th spicule (d) 4th frame of the 999th spicule

(e) 5th frame of the 999th spicule

(f) 6th frame of the 999th spicule

Figure 17: Identified 999th spicule in its life time.

Step 3:By following instructions from command window user you will be able to analyse any other spicule from the ROI.The statistical analysis of all the identified spicules are shown in Figure 18. A post-processed video of the ROI willbe automatically constructed and stored in the SSTC home folder. It should be noted that SSTC calculates lengthand width in pixels and lifetime as a number of frames.

14

(a) Statistical results of all spicules in the ROI(b) Post-processed video snapshot of ROI with back-ground removed

(c) Statistics of spicule sub-sample width

(d) Statistics of spicule sub-sample length

Figure 18: (a) Statistic results of all detected spicules in the ROI. (b) Post-processed video snapshot of ROI withbackground removed. (c) Statistics on width of spicules 1350 to 1770 detected in the ROI. (d) Statistics on thelength of all spicules 1350 to 1770 detected in ROI.

4 Example of coronal loops identification

Coronal loops are natural curvilinear features and therefore, as with solar spicules, they can also be detected by thepresent code by resetting the initial parameters. It is found that loop identification using SSTC are comparable with

15

other automated methods (see e.g., [5] ). To show the code performance for coronal loop identification we used thesame image as authors of [5] (i.e. ’TRACE 1998 0 19, 171A’) which is shown in Figure 19.

Figure 19: Original 171A TRACE image of 19 May 1998, 22:21 UT, with a size of 1024 x 1024 pixels. The blackcolour corresponds to high intensity fluxes. The circular white boundary is caused by the vignetting of the telescope(not to be confused with the solar limb) [5].

For analysis of this image parameters of SSTC should be set to:threshold filter=0.2,area down index=150,area up index=20000.

Then run extra step image anl.m.

Then: Step 1 KUUGA SSRU Image parameter testStep 2Step 3Step 4Step 5

The result of processing is shown in Figure 20.

16

(a) (b)

(c) (d)

(e)

Figure 20: (a) ROI of shown in Figure 19. (b) Image after applying contrast stretch methods. (c) Categorising pro-cess. (d) Different coronal loops are shown in different colours. (e) Post processing image of ROI with backgroundremoved.

In the region cell (see Figure 21) it is shown that 199 coronal loop structures are detected. This number is sensitiveto the initial parameter choice.

17

(a) (b)

Figure 21: (a) The number of detected coronal loops. (b) The length of 141th coronal loop.

Figure 22: The 141th detected coronal loop is shown in a white colour on the black image. The same loop is shownin details on the smaller sub-figure. In the sub-figure the contour of the loop is shown in blue, the axis as a blackdotted line and the centroids as red circles.

5 Release notes

SSTC version 1.0 (2019) can analyse and provide statistics on solar spicules or coronal loops identifiedin given solar imaging data.

6 Queries

Viktor Fedun (ACSE), v.fedun@sheffield.ac.ukYuyang Yuan (SoMaS, ACSE), YYuan26@sheffield.ac.uk, 1657139850@qq.comGary Verth (SoMaS), g.verth@sheffield.ac.uk

18

7 Citation in the literature

We acknowledge the Plasma Dynamics Group at the University of Sheffield for providing the Solar Spicule Track-ing Code (SSTC).

References

[1] Copyright (c) 2016, H.J. Sommer All rights reserved.http://uk.mathworks.com/matlabcentral/fileexchange/319-polygeom-m

[2] Copyright (c) 2016, Erik A Johnson All rights reserved.https://uk.mathworks.com/matlabcentral/fileexchange/278-arrow

[3] Copyright (c) 2012, John D’Errico All rights reserved.https://uk.mathworks.com/matlabcentral/fileexchange/34871-arclength

[4] C. Steger, An Unbiased Detector of Curvilinear Structures, IEEE Trans. Pattern Anal. Mach. Intell., vol. 20,no. 2, pp. 113-125, 1998.

[5] M. J. Aschwanden, J. K. Lee, G. A. Gary, M. Smith, and B. Inhester, Comparison of Five Numerical Codes forAutomated Tracing of Coronal Loops, Sol. Phys., vol. 248, no. 2, pp. 359-377, 2008.

19