Add functionality that allows users to draw polygons to define analysis regions

[leewujung]

The functionality should allow users to create custom analysis regions by drawing arbitrary polygons directly on the echogram. Users should be able to select multiple points on the echogram to define the vertices of each polygon.

The drawn polygons should:

• Be editable (users can adjust or remove points as needed)
• Support multiple polygons within a single session
• Be exportable in a format compatible with the Region Browser (i.e., include polygon vertices and associated metadata such as the time range)

Note

This issue was duplicated from uw-echospace/engine_echo_data_viz#2.
The functionality here can be part of the region browser in #219 .

Prototype

See this folder and the associated explanation for notebook prototype.

[Safwannn89]

Hi @leewujung,

Thank you for the quick feedback! I’m really excited to dive into the integration with #220.

Current Status:

• Region Browser with dropdown + Previous/Next navigation working
• Uses echoshader's built-in .echogram() function for multi-frequency display
• Loads regions from CSV with region_id and region_boundary columns
• Displays red polygon overlays on real S3 echogram data

Integration Plan for #220:
I'm thinking about the architecture - should editing be:

• Option A: Toggle mode within Region Browser (Browse ↔ Edit)

• Option B: Separate modular widget that can be composed with the browser

I'm leaning toward Option B for better modularity - what do you think?

Next Steps:

• I'll start prototyping the PolyDraw/PolyEdit integration using the current sample data structure
• Once you provide the Echoregions CSV samples and format documentation, I'll adapt the implementation to match
• This way, I can make progress while learning the drawing tools

I have Two Questions:
1.Which widget architecture do you prefer (integrated vs. modular)?
2.For the Echoregions CSV format you mentioned - will it follow the same structure as the current region_id + region_boundary format, or will there be additional metadata fields?

Waiting for:
Sample region CSV files and Echoregions storage format documentation

Looking forward to the sample data!

[leewujung]

@Safwannn89 : Thanks for the sketches and questions!

Looking at the options A and B you have, I kinda feel that maybe option A would be more natural, so it'll basically be a region browser with the functionality to edit the region boundaries. Maybe the user will always have the option to edit?? Having a toggle is nice too to avoid the risk of accidental edits.
@LOCEANlloydizard : What do you think? I feel it's pretty murky which parts should be modular and which parts should be integrated. We can discuss more when we meet tomorrow too.

For the CSV format: see code here that has the required columns:

    # Define the expected columns
    expected_columns = ["region_id", "time", "depth"]

The time and depth columns will be lists of numbers, like what's shown in the example notebook here: https://echoregions.readthedocs.io/en/latest/Regions2D_functionality.html#regions2d-as-a-dataframe
Note that here the regions2d.data is read in from an EVR file (it is a specialized plain text format of a popular proprietary echo data analysis software), but in the above I was referring to code that read in from an CSV file. We made regions2d.__init__ to be able to read in either an EVR or an CSV for flexibility.

Before I get the data ready for your test, you could get started using the data from the Echoregions notebook (I'll supply you with EVR files, so will be the same format).

[Safwannn89]

Hi @leewujung,

I've successfully implemented the integrated editing functionality for the Region Browser (Issue #220). I went with Option A as we discussed and fully migrated the backend to expect the Echoregions data format.

Here is a look at the new workflow:

1. Browse Mode (View-Only)
   The UI defaults to a clean, locked state. I updated the sidebar to use a dropdown + Previous/Next navigation, which will scale much better when we load hundreds of regions.

2. Edit Mode (Interactive)
   When you click Edit, the Actions section appears with Save/Reset/Export buttons. You can

• Click on the echogram to add vertices
• Drag vertices to move them
• Double-click vertices to delete them

3.The edited regions are saved back to the DataFrame in the proper Echoregions format (region_id, time as datetime64[ns], depth as float64).

Files
I've organized everything into 4 cells:

Cell 1: Setup and S3 connection
Cell 2: Sample data in Echoregions format
Cell 3: Parser for the numpy datetime/depth arrays
Cell 4: The interactive dashboard

All tested with the real S3 data and working smoothly.
Let me know if you'd like me to change anything or if you have feedback on the UI! I'm ready to integrate with the EVR files when you have them.

[LOCEANlloydizard]

Hi @Safwannn89 @leewujung,

Sorry for the delay in replying! Super exciting to see this taking shape, that’s really cool.
I’m glad you went with option A as well; I agree it feels more natural this way.

I have two small points for now:

1. Is there an option for a user to load back their saved regions? Apologies if I missed it, but I don’t see a button for that on the interface?
2. That brings me to a second point: do we have any kind of “foreign key” (in the relational database sense) to ensure that a user loads a file that makes sense for this data?

Cheers!

[Safwannn89]

Hii @LOCEANlloydizard @leewujung
Thanks for the feedback!

1. Loading saved regions:
   You're right - we currently only have Export. I'll add a "Load CSV" button that allows users to import previously saved regions back into the browser.
2. Validation:
   Good point about ensuring the loaded regions match the current echogram. I'll add validation that checks:

• Region timestamps fall within the echogram's time range
• CSV has the correct format (region_id, time, depth columns)
• Data types are valid (datetime64[ns] and float64)

I'll implement these and post an update. Let me know if you'd like any specific!

Thanks

[Safwannn89]

Hi @LOCEANlloydizard @leewujung

I've implemented both features:

1. Load CSV Button
   Added a file upload button in the Actions section that allows users to import previously saved regions.

2. Validation
   Implemented validation that checks:

• Region timestamps fall within the echogram's time range
• CSV has correct format (region_id, time, depth columns)
• Data types are valid (datetime64[ns], float64)

Testing
Valid CSV: Successfully loads and displays regions.

Invalid CSV (wrong time range): Correctly rejected with error message:

 Validation failed: Region 1 times (2017-07-31 to 2020-01-01) 
outside echogram range (2017-07-31 to 2017-07-31)

The validation acts as a "foreign key" check, ensuring loaded regions belong to the current echogram.

Please Review this
Thanks.

[LOCEANlloydizard]

Hi @Safwannn89, that’s really cool (and fast)!
To review it properly, it would be great if you could open a PR so we can have a look at the code and try it out?
Could you also reference this issue and 219 in the commit message? Cheers!

[Safwannn89]

Hi @LOCEANlloydizard,
Thanks for the feedback! I'll open a PR shortly with all the code so you can review and test it.
I'll make sure to reference both #220 and #219 in the commit message.

Thanks!