Refactor Region code to RegionState and RegionConverter

[pford]

Description

• What is implemented or fixed? Mention the linked issue(s), if any. Implements #1347

• How does this PR solve the issue? Give a brief summary.

  • Code maintenance: the Region class needed to be streamlined.
  • RegionState struct was moved to a separate file, with some Region functions now in the struct.
  • RegionConverter class contains code (formerly in Region) to convert the region to a non-reference image, either as the same region type or as a polygon approximation, and return it as casacore::LCRegion or casacore::Record.
  • Region is now only for the region in the reference image. It creates a RegionConverter when needed for matched images.
  • Other cleanup: unused methods and includes removed.
  • Testing: additional backend tests were created for reference and matched regions, to validate the refactor and for better code coverage.
  • Performance: to retrieve the Region as LCRegion or a Record, for all images (1) the control points were converted from pixel to world coordinates and used to create a casacore::WCRegion, (2) WCRegion::toLCRegion converts back to pixel coordinates, (3) (if requested) LCRegion::toRecord creates a Record. For the reference image, however, the conversion to world coordinates and back to pixel coordinates is unnecessary and adds time. This especially affects the performance of line spatial profiles and PV image generation where numerous regions are created along the line and their LCRegions are used for the statistics. Instead, for the reference file ID a Record is created from the control points, which can be returned as a Record for export or as LCRegion using LCRegion::fromRecord for analytics.

• Are there any companion PRs (frontend, protobuf)? No, backend change only

• Is there anything else that testers should know (e.g. exactly how to reproduce the issue)? The behavior should be unchanged by this refactor, except in small underlying details (e.g. LCRegion::toRecord returns the coordinates 1-based but creating the Record from control points is 0-based, as specified in the Record's "oneRel" field).

Checklist

• [x] changelog updated / ~no changelog update needed~
• [ ] e2e test passing / corresponding fix added / new e2e test created
• [ ] ICD test passing / corresponding fix added / new ICD test created
• [x] ~protobuf updated to the latest dev commit~ / no protobuf update needed
• [x] ~protobuf version bumped~ / protobuf version not bumped
• [x] added reviewers and assignee
• [x] added ZenHub estimate, milestone, and release

[kswang1029]

@pford Thanks for addressing the issues I found. All the four issues are fixed. There is one last thing: when exporting an annotation ellipse, the position angle seems having a small offset. this branch: ann ellipse [[17:56:21.28865, -021.57.23.2793], [4.0851arcsec, 2.5532arcsec], 0.00000250deg] coord=J2000, corr=[I], linewidth=2, linestyle=-, symsize=1, symthick=1, color=ffba01, font=Helvetica, fontsize=10, fontstyle=bold, usetex=false

dev: ann ellipse [[17:56:21.28865, -021.57.23.2793], [4.0851arcsec, 2.5532arcsec], 0.00000000deg] coord=J2000, corr=[I], linewidth=2, linestyle=-, symsize=1, symthick=1, color=ffba01, font=Helvetica, fontsize=10, fontstyle=bold, usetex=false

[pford]

@kswang1029 I tested this branch pam/1347_region_converter and the combined branch pam/combine_1347_1339_branches on Ubuntu and macOS 13.6, exporting ann ellipse to CRTF World in the reference image and a matched image. In all cases, the angle was 0.00000000deg.

[kswang1029]

@kswang1029 I tested this branch pam/1347_region_converter and the combined branch pam/combine_1347_1339_branches on Ubuntu and macOS 13.6, exporting ann ellipse to CRTF World in the reference image and a matched image. In all cases, the angle was 0.00000000deg.

Odd. I will do some extra multi-platform tests.

[kswang1029]

@pford I tried the following platforms but got exactly the same results (thus test failure):

• apple silicon - Ventura
• intel - Monterey
• intel - Ubuntu 22.04

What's your test platform? Any relevant libraries that we should compare their versions?

meanwhile I will check test workflow.

[kswang1029]

@pford I spotted a behavior about the PA of ellipse and ann ellipse. When we make it as "oblate", the PA is 0 deg. However, if we make it as "prolate", there will be a small shift in PA.

Could you see if you can reproduce this in your env please?

I confirm that with v4.1 PA is still 0deg.

[pford]

@kswang1029 fixed by using double instead of float for angle in ellipse record. More accurate when converted from rad to deg.

[github-actions[bot]]

Package	Line Rate	Health
src.Cache	72%	➖
src.DataStream	44%	➖
src.FileList	67%	➖
src.Frame	36%	❌
src.HttpServer	42%	➖
src.ImageData	28%	❌
src.ImageFitter	83%	✔
src.ImageGenerators	43%	➖
src.ImageStats	75%	✔
src.Logger	37%	❌
src.Main	52%	➖
src.Region	69%	➖
src.Session	4%	❌
src.Table	52%	➖
src.ThreadingManager	67%	➖
src.Timer	85%	✔
src.Util	40%	➖
Summary	46% (8589 / 18738)	➖