Clarify arguments used only when producing "web-optimized" COGs

[alexismanin]

Hi,

It looks like some arguments to cogeo.cog_translate function are only applied if web_optimized argument is set to True, like tms, zoom_level, etc.

I failed to see them as "specialized" arguments on first look, and I had to look at the function source code for a better understanding.

Therefore, I see two possible improvements:

• Either improve the function documentation to explicit which arguments are valid only for web-optimization
• Or rework the function input in a more structured way. For example, web_optimized could become a structure (pydantic setting or model) that holds all intended arguments, instead of them being scattered as direct function argument. In such case, we could aim for retro-compatibility by letting current arguments as they are, but deprecate them, and define web_optimized as the following UnionType: bool|str|TileMatrixSet|WebOptimizationSettings. When specified as:
  • bool, it would conserve the current behaviour. At term, when a breaking change would be possible or wanted, it could be restricted to the meaning "default WebMercatorQuad matrix set, with no zoom level configuration"
  • str: identifier or the path to a TileMatrixSet spec
  • TileMatrixSet : The tile matrix set to use
  • WebOptimizationSettings : a Pydantic setting holding any related configuration (tms, zoom level or zoom level strategy, etc.).

If any of the above suggestion looks good to you, I offer to submit a PR for it.

[vincentsarago]

👋 Bonjour @alexismanin

Thanks for starting this discussion.

Yes, I'm sorry about this. I think what happened is that when I started working on the WebOptimization part, there was only one option web_optimized and then when we enabled more options, we tried to follow GDAL COG options.

I think we could do:

• improve the documentation
• deprecate web_optimized option and change the logic to see if the tms option was passed (yeah one less option 🥳 )
• the tms option should always be of type morecantile.TileMatrixSet (it makes things way more simpler)
• for the other zoom_level_strategy, zoom_level, aligned_levels and resampling, I think just updating the documentation should be enough

[alexismanin]

Just a side-note: resampling does not seem bound to web-optimization, because it is used by rasterio warp (WarpedVRT), and that is done anyway.

If I understand well, no reprojection is configurable except through the tms argument, but the warp may still make sense if user has specified dtype parameter.
Although I am wondering if a warp operator that only change output dtype will perform any interpolation/resample.

In any case, I will give a try to your suggestion.

[vincentsarago]

@alexismanin, the VRT is used also when

• we want to override the nodata
• convert nodata/alpha to mask

but yeah the resampling option shouldn't have any effect when not using the web-optimization. I think I though at one point of adding the dst-crs option but this will conflict with the tms option so I preferred not to pursue.

Although I am wondering if a warp operator that only change output dtype will perform any interpolation/resample.

I hope not 😅 , I can also see that we didn't add tests for the dtype option

[vincentsarago]

I think we are good to close this 🙏 @alexismanin