Add `export_field_outline()` one liner export

[mferrera]

Currently field outlines are exported from RMS projects in the following way:

1. Define horizon and contacts, folder locations, polygon vertices limits
2. Convert horizon to xtgeo.Surface
3. For each contact 3.1. Convert contact to xtgeo.Surface 3.2 Process, mask, store to RMS project (QC step, optional) 3.3 Get boundary polygons, xtgeo.Polygons 3.4 Filter polygons with vertices < vertices limit 3.5 Export xtgeo.Polygons
   • https://github.com/equinor/fmu-dataio/blob/b30c170d7d76cab61d4b3eea86f7a1fb4ba9ca7f/src/fmu/dataio/providers/objectdata/_xtgeo.py#L123
   • https://github.com/equinor/xtgeo/blob/934e94c34b04f219d0211b611b01b9670d3f205a/src/xtgeo/xyz/polygons.py#L206

Simplification

We could explore grouping everything from step 2 into a single function and hide some details. A discussion of the arity of this function is still ongoing

export_field_outlines(
    project: Any,  # PRJ
    top_surface_name: str, # or RMS name, and create it behind the scenes. Horizon?
    top_surface_category: str, # folder name containing top surface. Horizon?
    contacts: list[str],  # TODO: Current topic of discussion
    global_config: str | Path = "path/to/global/config",
    vertical_domain: dict[str, str] = {"depth": "msl"},
    workflow: str = "rms/structural model",
    tagname: str = f"field_outline_(contact_name)",
)

Unanswered questions

• Should it also export contacts?
• How should contacts be provided if they can potentially be located in multiple places?
  • Clipboard
  • Generate 2d data
  • Horizon tree
  • ?
• Should contacts be provided as an xtgeo object, or as a name?
  • (name, category, subtype/type)
• Are there any problems if dataio handles the masking by itself? Is this a good standardization target?
• How should we handle polygon vertices limits?
• Would it be nice if the user did not have to import and use xtgeo at all to accomplish this export?
• field_outlines or field_lines? Should it match fault_lines/fault_outlines?

Summary discussion 9/9/2024

• We would prefer to keep the export "pure" -- no side effects, no modifying the RMS project (creating something)
• Polygons should be generated pre-export
• Contact should be provided as a string (?)
• We should consider the best way to standardize what is expected and what is generated
  • Ex: A folder must be provided?
  • Ex: HCPV maps required?

[tnatt]

Also we should discuss if we actually want to keep all of this functionality of creating the field_outlines inside this function, or if it should be more a pure export of pre-created field outlines.

The name of the function would indicate to users that this is a pure export, and it will be confusing atm. In addition these field outlines are often made in various ways

• using the intersection between top reservoir surface and contact surface
• using a saturation parameter in the grid to filter and create the outline
• using HCPV maps and create outline where HCPV is larger than 0
• manually
• etc

Also not everyone have contact surfaces easily available, they are often created from averaging FWL/GOC parameters in the grid.. but several models do not have these contact parameters but rather read contacts directly from global_variables into various scripts to update contacts in volumetrics/sw job etc.

[mferrera]

Do we and assets have a shared definition of a field outline?

Country outlines are a function of:

• country looking at the map,
• history,
• politics,
• ...,
• geography

The first argument may generate many permutations of the the same planet.

Field outlines are a function of:

• the asset?,
• contacts?,
• ...?,
• geology?

My understanding as a layman (i.e., ignorant) is that in Drogon at least, this is defined primarily by the second point. That said, Drogon is the first input to this function.

[ErichSuter]

@tnatt, as field outlines are made in various ways, is it recorded (e.g. as metadata) how they were made? And possibly why? I assume it would be nice to have this info directly in the geomodel, to make it easier to record for posterity and share between different users.

[mferrera]

Summary discussion 9/9/2024

• We would prefer to keep the export "pure" -- no side effects, no modifying the RMS project (creating something)
• Polygons should be generated pre-export
• Contact should be provided as a string (?)
• We should consider the best way to standardize what is expected and what is generated
  • Ex: A folder must be provided?
  • Ex: HCPV maps required?

(This text added to main issue)

[mferrera]

Summary discussion 10/9/2024

• We will seek to provide a standardized field outline function from another package, i.e. fmu-tools
  • This function will seek to store the field outline polygon in RMS' General 2D Data folder
  • It will store to some defaulted name
• The export function will take an "RMS path" to the outline polygon to export
  • By default to the General 2D Data folder
  • export_field_outline(project, ..., rms_path=[..., 'General 2D Data', 'field_outline'])

@jcrivenaes @tnatt is this an accurate summary before adding to the main issue comment?