Last modified: 29 February 2024

What does this warning mean?

WARNING: Zero length polygon line segment at (x,y) (index = z)

This message indicates that the CXC Datamodel (DM) has encountered a region containing a polygon that has a duplicate, adjacent pair of X,Y coordinates. This results in a polygon with a side having a length equal to zero. Before CIAO 4.8, this type of polygon could result in some pixels being incorrectly filtered and could result in problems with the calculation of the region's area. As of CIAO 4.8, this type of complex polygon is handled better though the area is a pixelated approximation. Therefore, users in general do not need to be concerned about this warning unless they are trying to use polygons with highly precise coordinates.

Users may encounter this type of "zero length" region as part of a normal user filter:

unix%  dmcopy img.fits[sky=polygon(3000,3000,3000,5000,3000,5000,5000,5000,5000,3000)]" out.fits
WARNING: Zero length polygon line segment at (3000,5000) (index = 1).
...

or may be encountered when the DM is accessing the data subspace stored in the file.

unix% dmcopy "acisf14520N002_evt2.fits[sky=region(acisf14520_000N002_fov1.fits)]" events_with_fov_subspace
unix% dmlist events_with_fov_subspace blocks
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
...
 
--------------------------------------------------------------------------------
Dataset: events_with_fov_subspace
--------------------------------------------------------------------------------
 
     Block Name                          Type         Dimensions
--------------------------------------------------------------------------------
Block    1: PRIMARY                        Null        
Block    2: EVENTS                         Table        15 cols x 259266   rows
Block    3: GTI1                           Table         2 cols x 1        rows
Block    4: GTI7                           Table         2 cols x 1        rows
Block    5: GTI3                           Table         2 cols x 1        rows
Block    6: GTI2                           Table         2 cols x 2        rows
Block    7: GTI0                           Table         2 cols x 1        rows

In this second example, the duplicate polygon points are the result of the limited numerical precision used to store the region subspace information. When a DM filter is applied, information about the filter is stored in the file's header keywords. The precision used to store this information may be such that closely spaced polygon points are stored as duplicate data points. In the example below, a field of view, FOV, file is used to filter the event file. Some points in the FOV file are very close and are written to the file's subspace as duplicate points. The "zero length" warning will be emitted whenever the DM accesses this region.

unix% dmlist acisf14520_000N002_fov1.fits"[cols x,y]" data,array,clean
#  POS(X,Y)[11]                            
      5069.8731317541      3986.6221794707
      4060.9887703561      4125.6853348714
      4023.4327250794      4125.6825301606
      3882.0581240740      3119.1275223318
      ...
      4002.0068195197      4106.9717942120
      4039.5618986631      4106.9757061631
      4039.5645155901      4106.9825114314
      4180.9752530170      5113.5335671620
      ...
      
unix% dmlist events_with_fov_subspace subspace | grep -i polygon
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
...
   8 sky                  Real4               Polygon(5069.87,3986.62,...)|Polygon(2993.1,4245.98,4002.01,4106.97,4039.56,4106.98,4039.56,4106.98,...
...   

As in this example, the "zero length" message may appear multiple times at the same location. The polygon is stored multiple times in the subspace (ie each subspace component), typically once for each CCD_ID. This warning is shown for each of those polygons individually. Note: In general, each CCD_ID does not have to have the same spatial filter which is why the information is stored separately for each chip. There may also be multiple pairs (or longer chains) of duplicate data points; this warning is printed for each.

This precision loss only occurs when the file is written and the subspace is read back in. Users that require highly precise polygon points should therefore apply such filters at the place in their analysis workflow where the data are extracted. For example, rather than filter and then bin as separate steps

unix% dmcopy "acisf14520N002_evt2.fits[sky=region(acisf14520_000N002_fov1.fits)]" events_with_fov_subspace
unix% dmextract "events_with_fov_subspace[sky=circle(4096,4096,10)][bin pi]" spectrum
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
WARNING: Zero length polygon line segment at (4039.56,4106.98) (index = 2).
...

Users that require precise polygon points should filter and bin at the same step

unix% dmextract "acisf14520N002_evt2.fits[sky=region(acisf14520_000N002_fov1.fits)][sky=circle(4096,4096,10)][bin pi]" spectrum2