geocontour.contourtrace module

Functions for tracing a contour on a lat/lon grid from an input mask

geocontour.contourtrace.square(mask, latitudes=None, longitudes=None, direction='cw', start='auto', stop='either', startvisits=3, checkconn=False, remcontourrepeat=True, remsearchrepeat=False, closecontour=True)

Find the contour of a mask using the square tracing algorithm

Also known as:

  • Papert’s turtle algorithm

  • simple boundary follower (SBF)

Parameters:

  • mask (ndarray) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • latitudes (ndarray, optional) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray, optional) – 1D Nx1 array of longitude points (degrees)

  • direction ({'cw', 'ccw'}, default='cw') – select the direction of contour tracing

  • start ({'auto', array_like}, default='auto') –

    either a selection for automatic start cell assignment or a manual assignment via a 2x2 array describing the start cell and orientation

    row 1: indices of the start cell

    e.g. for start cell [2,3] second row (lat) and third column (lon)

    row 2: the start orientation

    e.g. orientation [0,1] points right, [1,0] points down

  • stop ({'Elisoff', 'Nvisits', 'either'}, default='either') –

    selector for the stopping criterion

    Elisoff

    stops when the start cell has been re-visited with the same orientation as started with

    Nvisits

    stops when the start cell has been re-visited N number of times (N set by startvisits parameter)

    either

    stops when either Elisoff or Nvisits has been satisfied

  • startvisits (int, default=3) – the number of times re-visiting the start cell will trigger an end to the search

  • checkconn (bool, default=False) – select whether to check connectivity and warn the user of potential issues, default=False

  • remcontourrepeat (bool, default=True) – select whether to remove consecutive repeating cells in the output contour

  • remsearchrepeat (bool, default=False) – select whether to remove consecutive repeating cells in the output contoursearch

  • closecontour (bool, default=True) – select whether to close the output contour (first cell = last cell)

Returns:

  • contour (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

See also

geocontour.contourutil.findstart, geocontour.contourutil.setstop, moore, moore_imp, pavlidis, pavlidis_imp, MSBF, ISBF, TSR

Notes

  • If latitudes/longitudes not provided, returned contour/contoursearch will be indices of the input mask

  • startvisits parameter will only be utilized when stop parameter is set to ‘Nvisits’ or ‘either’

References

Ghuneim, A.G. (2000). Contour Tracing. McGill University. <https://www.imageprocessingplace.com/downloads_V3/root_downloads/tutorials/contour_tracing_Abeer_George_Ghuneim/alg.html>

Gose, E., Johnsonbaugh, R., & Jost, S. (1996). Pattern recognition and image analysis. Prentice Hall PTR.

Papert, S. (1973). Uses of Technology to Enhance Education (No. 298; Artificial Intelligence). Massachusetts Institute of Technology. <https://dspace.mit.edu/handle/1721.1/6213>

Seo, J., Chae, S., Shim, J., Kim, D., Cheong, C., & Han, T.-D. (2016). Fast Contour-Tracing Algorithm Based on a Pixel-Following Method for Image Sensors. Sensors, 16(3), 353. <https://doi.org/10.3390/s16030353>

Toussaint, G.T. (2010). Grids Connectivity and Contour Tracing [Lesson Notes]. McGill University. <http://www-cgrl.cs.mcgill.ca/~godfried/teaching/mir-reading-assignments/Chapter-2-Grids-Connectivity-Contour-Tracing.pdf>

geocontour.contourtrace.moore(mask, latitudes=None, longitudes=None, direction='cw', start='auto', stop='either', startvisits=3, remcontourrepeat=True, remsearchrepeat=False, closecontour=True)

Find the contour of a mask using the Moore neighbor tracing algorithm

Parameters:

  • mask (ndarray) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • latitudes (ndarray, optional) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray, optional) – 1D Nx1 array of longitude points (degrees)

  • direction ({'cw', 'ccw'}, default='cw') – select the direction of contour tracing

  • start ({'auto', array_like}, default='auto') –

    either a selection for automatic start cell assignment or a manual assignment via a 2x2 array describing the start cell and orientation

    row 1: indices of the start cell

    e.g. for start cell [2,3] second row (lat) and third column (lon)

    row 2: the start orientation

    e.g. orientation [0,1] points right, [1,0] points down

  • stop ({'Elisoff', 'Nvisits', 'either'}, default='either') –

    selector for the stopping criterion

    Elisoff

    stops when the start cell has been re-visited with the same orientation as started with

    Nvisits

    stops when the start cell has been re-visited N number of times (N set by startvisits parameter)

    either

    stops when either Elisoff or Nvisits has been satisfied

  • startvisits (int, default=3) – the number of times re-visiting the start cell will trigger an end to the search

  • remcontourrepeat (bool, default=True) – select whether to remove consecutive repeating cells in the output contour

  • remsearchrepeat (bool, default=False) – select whether to remove consecutive repeating cells in the output contoursearch

  • closecontour (bool, default=True) – select whether to close the output contour (first cell = last cell)

Returns:

  • contour (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

See also

geocontour.contourutil.findstart, geocontour.contourutil.setstop, square, moore_imp, pavlidis, pavlidis_imp, MSBF, ISBF, TSR

Notes

  • If latitudes/longitudes not provided, returned contour/contoursearch will be indices of the input mask

  • startvisits parameter will only be utilized when stop parameter is set to ‘Nvisits’ or ‘either’

References

Ghuneim, A.G. (2000). Contour Tracing. McGill University. <https://www.imageprocessingplace.com/downloads_V3/root_downloads/tutorials/contour_tracing_Abeer_George_Ghuneim/alg.html>

Toussaint, G.T. (2010). Grids Connectivity and Contour Tracing [Lesson Notes]. McGill University. <http://www-cgrl.cs.mcgill.ca/~godfried/teaching/mir-reading-assignments/Chapter-2-Grids-Connectivity-Contour-Tracing.pdf>

geocontour.contourtrace.moore_imp(mask, latitudes=None, longitudes=None, direction='cw', start='auto', stop='either', startvisits=3, remcontourrepeat=True, remsearchrepeat=False, closecontour=True)

Find the contour of a mask using an improved Moore neighbor tracing algorithm that reliably captures inside corners

Parameters:

  • mask (ndarray) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • latitudes (ndarray, optional) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray, optional) – 1D Nx1 array of longitude points (degrees)

  • direction ({'cw', 'ccw'}, default='cw') – select the direction of contour tracing

  • start ({'auto', array_like}, default='auto') –

    either a selection for automatic start cell assignment or a manual assignment via a 2x2 array describing the start cell and orientation

    row 1: indices of the start cell

    e.g. for start cell [2,3] second row (lat) and third column (lon)

    row 2: the start orientation

    e.g. orientation [0,1] points right, [1,0] points down

  • stop ({'Elisoff', 'Nvisits', 'either'}, default='either') –

    selector for the stopping criterion

    Elisoff

    stops when the start cell has been re-visited with the same orientation as started with

    Nvisits

    stops when the start cell has been re-visited N number of times (N set by startvisits parameter)

    either

    stops when either Elisoff or Nvisits has been satisfied

  • startvisits (int, default=3) – the number of times re-visiting the start cell will trigger an end to the search

  • remcontourrepeat (bool, default=True) – select whether to remove consecutive repeating cells in the output contour

  • remsearchrepeat (bool, default=False) – select whether to remove consecutive repeating cells in the output contoursearch

  • closecontour (bool, default=True) – select whether to close the output contour (first cell = last cell)

Returns:

  • contour (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

See also

geocontour.contourutil.findstart, geocontour.contourutil.setstop, square, moore, pavlidis, pavlidis_imp, MSBF, ISBF, TSR

Notes

  • If latitudes/longitudes not provided, returned contour/contoursearch will be indices of the input mask

  • startvisits parameter will only be utilized when stop parameter is set to ‘Nvisits’ or ‘either’

geocontour.contourtrace.pavlidis(mask, latitudes=None, longitudes=None, direction='cw', start='auto', stop='Nvisits', startvisits=1, remcontourrepeat=True, remsearchrepeat=False, closecontour=True)

Find the contour of a mask using the Pavlidis algorithm

Parameters:

  • mask (ndarray) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • latitudes (ndarray, optional) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray, optional) – 1D Nx1 array of longitude points (degrees)

  • direction ({'cw', 'ccw'}, default='cw') – select the direction of contour tracing

  • start ({'auto', array_like}, default='auto') –

    either a selection for automatic start cell assignment or a manual assignment via a 2x2 array describing the start cell and orientation

    row 1: indices of the start cell

    e.g. for start cell [2,3] second row (lat) and third column (lon)

    row 2: the start orientation

    e.g. orientation [0,1] points right, [1,0] points down

  • stop ({'Elisoff', 'Nvisits', 'either'}, default='either') –

    selector for the stopping criterion

    Elisoff

    stops when the start cell has been re-visited with the same orientation as started with

    Nvisits

    stops when the start cell has been re-visited N number of times (N set by startvisits parameter)

    either

    stops when either Elisoff or Nvisits has been satisfied

  • startvisits (int, default=1) – the number of times re-visiting the start cell will trigger an end to the search

  • remcontourrepeat (bool, default=True) – select whether to remove consecutive repeating cells in the output contour

  • remsearchrepeat (bool, default=False) – select whether to remove consecutive repeating cells in the output contoursearch

  • closecontour (bool, default=True) – select whether to close the output contour (first cell = last cell)

Returns:

  • contour (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

See also

geocontour.contourutil.findstart, geocontour.contourutil.setstop, square, moore, moore_imp, pavlidis_imp, MSBF, ISBF, TSR

Notes

  • If latitudes/longitudes not provided, returned contour/contoursearch will be indices of the input mask

  • startvisits parameter will only be utilized when stop parameter is set to ‘Nvisits’ or ‘either’

References

Ghuneim, A.G. (2000). Contour Tracing. McGill University. <https://www.imageprocessingplace.com/downloads_V3/root_downloads/tutorials/contour_tracing_Abeer_George_Ghuneim/alg.html>

Pavlidis, T. (1982) Algorithms for Graphics and Image Processing. Computer Science Press, New York, NY. <https://doi.org/10.1007/978-3-642-93208-3>

geocontour.contourtrace.pavlidis_imp(mask, latitudes=None, longitudes=None, direction='cw', start='auto', stop='Nvisits', startvisits=1, remcontourrepeat=True, remsearchrepeat=False, closecontour=True)

Find the contour of a mask using an improved Pavlidis algorithm that reliably captures inside corners

Parameters:

  • mask (ndarray) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • latitudes (ndarray, optional) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray, optional) – 1D Nx1 array of longitude points (degrees)

  • direction ({'cw', 'ccw'}, default='cw') – select the direction of contour tracing

  • start ({'auto', array_like}, default='auto') –

    either a selection for automatic start cell assignment or a manual assignment via a 2x2 array describing the start cell and orientation

    row 1: indices of the start cell

    e.g. for start cell [2,3] second row (lat) and third column (lon)

    row 2: the start orientation

    e.g. orientation [0,1] points right, [1,0] points down

  • stop ({'Elisoff', 'Nvisits', 'either'}, default='either') –

    selector for the stopping criterion

    Elisoff

    stops when the start cell has been re-visited with the same orientation as started with

    Nvisits

    stops when the start cell has been re-visited N number of times (N set by startvisits parameter)

    either

    stops when either Elisoff or Nvisits has been satisfied

  • startvisits (int, default=1) – the number of times re-visiting the start cell will trigger an end to the search

  • remcontourrepeat (bool, default=True) – select whether to remove consecutive repeating cells in the output contour

  • remsearchrepeat (bool, default=False) – select whether to remove consecutive repeating cells in the output contoursearch

  • closecontour (bool, default=True) – select whether to close the output contour (first cell = last cell)

Returns:

  • contour (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

See also

geocontour.contourutil.findstart, geocontour.contourutil.setstop, square, moore, moore_imp, pavlidis, MSBF, ISBF, TSR

Notes

  • If latitudes/longitudes not provided, returned contour/contoursearch will be indices of the input mask

  • startvisits parameter will only be utilized when stop parameter is set to ‘Nvisits’ or ‘either’

geocontour.contourtrace.MSBF(mask, latitudes=None, longitudes=None, direction='cw', start='auto', stop='either', startvisits=3, remcontourrepeat=True, remsearchrepeat=False, closecontour=True)

Find the contour of a mask using the modified simple boundary following algorithm

Parameters:

  • mask (ndarray) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • latitudes (ndarray, optional) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray, optional) – 1D Nx1 array of longitude points (degrees)

  • direction ({'cw', 'ccw'}, default='cw') – select the direction of contour tracing

  • start ({'auto', array_like}, default='auto') –

    either a selection for automatic start cell assignment or a manual assignment via a 2x2 array describing the start cell and orientation

    row 1: indices of the start cell

    e.g. for start cell [2,3] second row (lat) and third column (lon)

    row 2: the start orientation

    e.g. orientation [0,1] points right, [1,0] points down

  • stop ({'Elisoff', 'Nvisits', 'either'}, default='either') –

    selector for the stopping criterion

    Elisoff

    stops when the start cell has been re-visited with the same orientation as started with

    Nvisits

    stops when the start cell has been re-visited N number of times (N set by startvisits parameter)

    either

    stops when either Elisoff or Nvisits has been satisfied

  • startvisits (int, default=3) – the number of times re-visiting the start cell will trigger an end to the search

  • checkconn (bool, default=False) – select whether to check connectivity and warn the user of potential issues, default=False

  • remcontourrepeat (bool, default=True) – select whether to remove consecutive repeating cells in the output contour

  • remsearchrepeat (bool, default=False) – select whether to remove consecutive repeating cells in the output contoursearch

  • closecontour (bool, default=True) – select whether to close the output contour (first cell = last cell)

Returns:

  • contour (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

See also

geocontour.contourutil.findstart, geocontour.contourutil.setstop, square, moore, moore_imp, pavlidis, pavlidis_imp, ISBF, TSR

Notes

  • If latitudes/longitudes not provided, returned contour/contoursearch will be indices of the input mask

  • startvisits parameter will only be utilized when stop parameter is set to ‘Nvisits’ or ‘either’

References

Cheong, C.-H., & Han, T.-D. (2006). Improved Simple Boundary Following Algorithm. Journal of KIISE: Software and Applications, 33(4), 427–439. <https://koreascience.kr/article/JAKO200622219415761.pdf>

Cheong, C.-H., Seo, J., & Han, T.-D. (2006). Advanced Contour Tracing Algorithms based on Analysis of Tracing Conditions. Proceedings of the 33rd KISS Fall Conference, 33, 431–436. <https://koreascience.kr/article/CFKO200614539217302.pdf>

Gose, E., Johnsonbaugh, R., & Jost, S. (1996). Pattern recognition and image analysis. Prentice Hall PTR.

geocontour.contourtrace.ISBF(mask, latitudes=None, longitudes=None, direction='cw', start='auto', stop='either', startvisits=3, remcontourrepeat=True, remsearchrepeat=False, closecontour=True)

Find the contour of a mask using the improved simple boundary following algorithm

Parameters:

  • mask (ndarray) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • latitudes (ndarray, optional) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray, optional) – 1D Nx1 array of longitude points (degrees)

  • direction ({'cw', 'ccw'}, default='cw') – select the direction of contour tracing

  • start ({'auto', array_like}, default='auto') –

    either a selection for automatic start cell assignment or a manual assignment via a 2x2 array describing the start cell and orientation

    row 1: indices of the start cell

    e.g. for start cell [2,3] second row (lat) and third column (lon)

    row 2: the start orientation

    e.g. orientation [0,1] points right, [1,0] points down

  • stop ({'Elisoff', 'Nvisits', 'either'}, default='either') –

    selector for the stopping criterion

    Elisoff

    stops when the start cell has been re-visited with the same orientation as started with

    Nvisits

    stops when the start cell has been re-visited N number of times (N set by startvisits parameter)

    either

    stops when either Elisoff or Nvisits has been satisfied

  • startvisits (int, default=3) – the number of times re-visiting the start cell will trigger an end to the search

  • checkconn (bool, default=False) – select whether to check connectivity and warn the user of potential issues, default=False

  • remcontourrepeat (bool, default=True) – select whether to remove consecutive repeating cells in the output contour

  • remsearchrepeat (bool, default=False) – select whether to remove consecutive repeating cells in the output contoursearch

  • closecontour (bool, default=True) – select whether to close the output contour (first cell = last cell)

Returns:

  • contour (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

See also

geocontour.contourutil.findstart, geocontour.contourutil.setstop, square, moore, moore_imp, pavlidis, pavlidis_imp, MSBF, TSR

Notes

  • If latitudes/longitudes not provided, returned contour/contoursearch will be indices of the input mask

  • startvisits parameter will only be utilized when stop parameter is set to ‘Nvisits’ or ‘either’

References

Cheong, C.-H., & Han, T.-D. (2006). Improved Simple Boundary Following Algorithm. Journal of KIISE: Software and Applications, 33(4), 427–439. <https://koreascience.kr/article/JAKO200622219415761.pdf>

Cheong, C.-H., Seo, J., & Han, T.-D. (2006). Advanced Contour Tracing Algorithms based on Analysis of Tracing Conditions. Proceedings of the 33rd KISS Fall Conference, 33, 431–436. <https://koreascience.kr/article/CFKO200614539217302.pdf>

Seo, J., Chae, S., Shim, J., Kim, D., Cheong, C., & Han, T.-D. (2016). Fast Contour-Tracing Algorithm Based on a Pixel-Following Method for Image Sensors. Sensors, 16(3), 353. <https://doi.org/10.3390/s16030353>

geocontour.contourtrace.TSR(mask, latitudes=None, longitudes=None, direction='cw', start='auto', stop='either', startvisits=3, remcontourrepeat=True, remsearchrepeat=False, closecontour=True)

Find the contour of a mask using the two-step representative tracing algorithm

Parameters:

  • mask (ndarray) – 2D MxN bool array where M=len(latitudes) and N=len(longitudes)

  • latitudes (ndarray, optional) – 1D Nx1 array of latitude points (degrees)

  • longitudes (ndarray, optional) – 1D Nx1 array of longitude points (degrees)

  • direction ({'cw', 'ccw'}, default='cw') – select the direction of contour tracing

  • start ({'auto', array_like}, default='auto') –

    either a selection for automatic start cell assignment or a manual assignment via a 2x2 array describing the start cell and orientation

    row 1: indices of the start cell

    e.g. for start cell [2,3] second row (lat) and third column (lon)

    row 2: the start orientation

    e.g. orientation [0,1] points right, [1,0] points down

  • stop ({'Elisoff', 'Nvisits', 'either'}, default='either') –

    selector for the stopping criterion

    Elisoff

    stops when the start cell has been re-visited with the same orientation as started with

    Nvisits

    stops when the start cell has been re-visited N number of times (N set by startvisits parameter)

    either

    stops when either Elisoff or Nvisits has been satisfied

  • startvisits (int, default=3) – the number of times re-visiting the start cell will trigger an end to the search

  • checkconn (bool, default=False) – select whether to check connectivity and warn the user of potential issues, default=False

  • remcontourrepeat (bool, default=True) – select whether to remove consecutive repeating cells in the output contour

  • remsearchrepeat (bool, default=False) – select whether to remove consecutive repeating cells in the output contoursearch

  • closecontour (bool, default=True) – select whether to close the output contour (first cell = last cell)

Returns:

  • contour (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the edge of a mask

  • contoursearch (ndarray) – 2D Nx2 array of ordered latitude/longitude points (degrees) describing the cells searched during contour tracing

See also

geocontour.contourutil.findstart, geocontour.contourutil.setstop, square, moore, moore_imp, pavlidis, pavlidis_imp, MSBF, ISBF

Notes

  • If latitudes/longitudes not provided, returned contour/contoursearch will be indices of the input mask

  • startvisits parameter will only be utilized when stop parameter is set to ‘Nvisits’ or ‘either’

References

Seo, J., Chae, S., Shim, J., Kim, D., Cheong, C., & Han, T.-D. (2016). Fast Contour-Tracing Algorithm Based on a Pixel-Following Method for Image Sensors. Sensors, 16(3), 353. <https://doi.org/10.3390/s16030353>