diff --git a/src/ocrmypdf/helpers.py b/src/ocrmypdf/helpers.py index 180e5dd1..404184e9 100644 --- a/src/ocrmypdf/helpers.py +++ b/src/ocrmypdf/helpers.py @@ -82,14 +82,12 @@ class Resolution(Generic[T]): return isfinite(self.x) and isfinite(self.y) return True - @property - def mean(self) -> float: - """Return the harmonic mean of x and y. + def to_scalar(self) -> float: + """Return the harmonic mean of x and y as a 1D approximation. - The harmonic mean is used because it is the correct mean to use for - averaging rates, such as pixels per inch. If a calculation requires a single - value instead of a pair of values, the harmonic mean is the correct value to - use. + In most cases, Resolution is 2D, but typically it is "square" (x == y) and + can be approximated as a single number. When not square, the harmonic mean + is used to approximate the 2D resolution as a single number. """ return harmonic_mean([self.x, self.y]) @@ -119,7 +117,7 @@ class Resolution(Generic[T]): def __repr__(self): # pragma: no cover """Return a repr() of the resolution.""" - return f"Resolution({self.x}×{self.y} dpi)" + return f"Resolution({self.x!r}, {self.y!r})" def __eq__(self, other): """Return True if the resolution is equal to another resolution.""" diff --git a/src/ocrmypdf/pdfinfo/info.py b/src/ocrmypdf/pdfinfo/info.py index 73cc07ee..69f06c52 100644 --- a/src/ocrmypdf/pdfinfo/info.py +++ b/src/ocrmypdf/pdfinfo/info.py @@ -758,10 +758,20 @@ class PageResolutionInfo(NamedTuple): """Information about the resolution of a page.""" average_to_max_dpi_ratio: float - """The average DPI of the page divided by the maximum DPI of the page.""" + """The average DPI of the page divided by the maximum DPI of the page. + + This indicates the intensity of the resolution variation on the page. + + If the average is 1.0 or close to 1.0, has all of its content at a uniform + resolution. If the average is much lower than 1.0, some content is at a + higher resolution than the rest of the page. + """ area_ratio: float - """The maximum DPI area of the page divided by the total drawn area.""" + """The maximum-DPI area of the page divided by the total drawn area. + + This indicates the prevalence of high-resolution content on the page. + """ class PageInfo: @@ -966,13 +976,11 @@ class PageInfo: Vector graphics and text are ignored. - A ratio of 1.0 means that all images are the same DPI. - A large ratio indicates high DPI content. - A ratio of less than 1.0 is not possible. - Returns None if there is no meaningful DPI for the page. """ - image_dpis = [image.dpi.hypot for image in self._images if image.renderable] + image_dpis = [ + image.dpi.to_scalar() for image in self._images if image.renderable + ] image_areas = [image.printed_area for image in self._images if image.renderable] total_drawn_area = sum(image_areas) if total_drawn_area == 0: