Add functionality to create STAC Items derived from other STAC Items

[matthewhanson]

If a user wants to create a downstream product from existing STAC Items they should be able to create a new STAC Item for it.

A derived_from function should create a new STAC Item based on 1 or more existing items, and link to the existing ones using a derived_from link.

The case where a single Item is produced from a single the geometry and datetime would carry over, but do platform, or instruments? These are derived products, should they reference the original sensor? And what about extensions that may be in use? Do the derived products also use spectral bands (eo extension) or polarizations (sar extension)? I think we can come up with a reasonable list of fields that make sense to carry over.

In the case where you want to derive a single Item from multiple other Items it's much different, and probably deserves a separate function. What is the new datetime if based on Items with different datetimes? If the geometries don't match is the new geometry an intersection of all the input geometries (WARNING additional dependency may be required if this is the case)

[matthewhanson]

Put some more thought into what a create_derived_item() function should do.

Parameters:

• items: an array of items
• id: an new ID must be provided
• collection: a collection, if not provided do not set
• geometry: if not provided geometry would be a Multi-geometry of whatever type the source items are. If mixed, throw error
• datetime: an optional parameter specifying how to calculate the new datetime, e.g., first, last, midpoint

The function would:

• create new STAC Item with provided ID, geometry
• Calc geometry if not provided
• set start_datetime and end_datetime based on the input STAC Items
• set datetime based on input option, or null
• add links with rel=derived_from equal to all the items source self link (if available)
• carry over all properties that are the same across all items
• resulting item would have 0 assets and only derived_from links

[jsignell]

I am wondering if it would be more ergonomic to have a method like set_derived_from. So you would create the new item using Item(... and then do item.set_derived_from(original_item). It could just set the derived_from link. I know that gets rid of a lot of the magic, but it does seem to match existing patterns and it would put the burden (of calculating or inheriting the geometry for instance) on the user.

[gadomski]

I also don't know the use-case for the many->one conversion. I haven't seen that pattern much in the wild. @matthewhanson can you provide more information about that use-case, since it adds so much complexity to this ticket (one->one is pretty chill I think).

I am wondering if it would be more ergonomic to have a method like set_derived_from.

Agreed, it matches the set_collection pattern, and if we only need one->one functionality, a user could get everything they need from:

new_item = item.clone()
new_item.set_derived_from(item)

[jsignell]

I'm going to start work on a PR to add a .set_derived_from method to pystac.Item