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