Clarification and Verification Needed for 'max_size' Parameter in /cog Endpoint

[kbae1230]

Hi there. My name is KBAE and data engineer.
I've been using this amazing library and have encountered some questions.

In the /cog documentation (/cog docs), it mentions a parameter called max_size. However, when checking the /cog/statistics endpoint, the default value for max_size is stated as 1024, but this information doesn't seem to reflect in the actual codebase. During testing, differences were observed when using 1024 as the argument and when not. It would be beneficial to verify this inconsistency.

Additionally, clarity is needed regarding what max_size precisely represents. Finding information about its units and the nature of the data it refers to has proven difficult in the documentation.

Your attention to this matter would be greatly appreciated.

[vincentsarago]

dear @kbae1230

in the documentation (https://developmentseed.org/titiler/endpoints/cog/#statistics) we say;

max_size (int): Max image size from which to calculate statistics, default is 1024.

in the code base:

titiler/src/titiler/core/titiler/core/factory.py

Lines 405 to 415 in ffd67af

	def statistics(
	src_path=Depends(self.path_dependency),
	layer_params=Depends(self.layer_dependency),
	dataset_params=Depends(self.dataset_dependency),
	image_params=Depends(self.img_preview_dependency),
	post_process=Depends(self.process_dependency),
	stats_params=Depends(self.stats_dependency),
	histogram_params=Depends(self.histogram_dependency),
	reader_params=Depends(self.reader_dependency),
	env=Depends(self.environment_dependency),
	):

the statistics endpoint has couple of dependencies ☝️, one of them is the image_params

titiler/src/titiler/core/titiler/core/factory.py

Line 409 in ffd67af

image_params=Depends(self.img_preview_dependency),

which default to

titiler/src/titiler/core/titiler/core/dependencies.py

Lines 337 to 348 in ffd67af

	@dataclass
	class PreviewParams(DefaultDependency):
	"""Common Preview parameters."""
	max_size: Annotated[int, "Maximum image size to read onto."] = 1024
	height: Annotated[Optional[int], "Force output image height."] = None
	width: Annotated[Optional[int], "Force output image width."] = None
	def __post_init__(self):
	"""Post Init."""
	if self.width and self.height:
	self.max_size = None

where 1024 is defined as default for the max-size

During testing, differences were observed when using 1024 as the argument and when not.

Can you share a reproducible example, passing or not passing max_size=1024 shouldn't have any influence when not passing width and height parameters (https://github.com/cogeotiff/rio-tiler/blob/main/rio_tiler/reader.py#L129-L133)

[kbae1230]

Thank you for your response. I didn't use width and height arguments. I only utilized max_size, and discrepancies arose. Let me illustrate the COG API calls. The first file was made with a max_size of 1024, while the second one had no value specified(expected as default 1024). It's the same image on both sides.

1. -> input 1024
2. -> no value

In the first case, the image was loaded correctly, but an error occurred in the second case. Even though the default is 1024, why is there a difference between explicitly inputting 1024 and relying on the default?
Upon inspecting the code as suggested, no issues were apparent.

Additionally, could we delve a bit deeper into the unit of max_size and what values it represents? I'm curious if specifying the max_size argument when calling COG with large images prevents errors.

[vincentsarago]

🤔 can you share the titiler version you are using, and also the full API call you are doing?

I assumed you were using the /statistics [GET] endpoint but maybe you are using the /statistics [POST] with a GeoJSON feature, for which we don't have a default max_size set (https://github.com/developmentseed/titiler/blob/main/src/titiler/core/titiler/core/dependencies.py#L351-L362).

Additionally, could we delve a bit deeper into the unit of max_size and what values it represents?

The unit is in pixel/cells, it represent the maximum size (height or width) in which we wan to read the data into. This is to avoid having to fetch the full file. This is up to the user to set in the POST endpoint because we assume people usually want access the full resolution data when they want zonal statistics.

[kbae1230]

I confirmed that the 'max_size' parameter is not set a default in REST API post call. Additionally, I have also clarified the units and representation of the argument.
Thanks to your detailed and kind explanation, all my questions have been resolved although I was mistaken some of it.