hypothesis / hypothesis/client
Capture page number and bounding box of selection for PDF annotations
- Dominant language
- Mustache
- Stars
- 730
- Forks
- 224
- PR merge metrics
- No merged PRs in 30d
Description
_Update 2024-01-25: Page numbers are now captured (https://github.com/hypothesis/client/pull/5987). Bounding boxes are not._
For annotations on PDFs we currently capture text position and text quote selectors. A problem with these types of selectors is that they refer to text which has been extracted by viewer-specific logic, rather than "native" coordinates in the PDF which are independent of the viewer. This leads to some challenges:
- Anchoring the quotes and position selectors in a non-PDF.js environment may be challenging because the extracted text may be different
- Changes in PDF.js versions can alter the rendered text. This means that the client's anchoring needs to do some [expensive](https://github.com/hypothesis/client/pull/3706) work, including extracting text of pages which do not include the annotation, in order to tolerate such differences.
- In some PDFs the extracted text may be very poor (eg. if the selected text is an equation) and thus not very useful for display as a quote
- We don't know what page the annotation is on unless we have the PDF and until the annotations are anchored. This means that we can't show page number information when listing annotations in the Notebook or activity pages.
I propose that the client should start capturing a selector for PDF annotations which captures a "native", viewer independent, representation of the selection.
## PDF region selector proposal
Here is a concrete proposal for a `PDFRegionSelector` for this purpose. It describes a list of rectangular regions in PDF page cooordinates (ie. in the coordinate system that the PDF format uses internally to position things within a page). Each rect consists of a page number and X and Y coordinates defining the edges of the region.
```js
{
type: "PDFRegionSelector",
region: [
{ page: 1, x1: 100, x2: 200, y1: 100, y2: 200 },
{ page: 2, x1: 205, x2: 300, y1: 100, y2: 200 },
]
}
```
Currently the client only supports selectors that all refer to the same page. To support that the selector could use just a single `pageNumber` property. However there are use cases for selections that span multiple pages (eg. to select a sentence that is split over two pages), so recording the page number per region is forward compatible.
This initial proposal does not support non-rectangular regions. We could add that in future by adding a new type of entry in the `region` list which replaces the `x1`,`x2`,`y1`,`y2` properties with an alternate shape description (eg. a `path` that is a list of x, y coordinate pairs, similar to an SVG path.)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.