What is the quads property in Core.DocumentViewer.SearchResult?

[jamesl]

WebViewer Version:

Do you have an issue with a specific file(s)? No
Can you reproduce using one of our samples or online demos? No
Are you using the WebViewer server? No
Does the issue only happen on certain browsers? No
Is your issue related to a front-end framework? No
Is your issue related to annotations? No

Please give a brief summary of your issue:
(Think of this as an email subject)
When calling Core.DocumentViewer.getPageSearchResults, your documentation says it returns “SearchResult array Core.DocumentViewer.SearchResult” of type object.

When I search for “SearchResult” in your docs, I only see Core.DocumentViewer.SearchResults (note the plural form). But most of the documented properties match what I’m seeing while debugging our app so I’ll go with it.

Now, there is one property in there named “quads.” What is this? I first thought this should be Core.Math.Quad but its properties in the actual object do not match what’s documented. I also found an entry for Core.Annotations.TextMarkupAnnotation.Quads in your docs but there is absolutely no information on that entry.

Here is what I see in our app. This is from the return value of Core.DocumentViewer.getPageSearchResults:

So what is the type of these objects in the “quad” array? What is Sx, Tx, Vx, Wx, ka, la, ma, and oa?

Furthermore, I found this comment in another topic which shows that these objects have a getPoints method. I can indeed call this method and it looks like it returns Core.Math.Quad objects which are actually useful. But when I search for “getPoints” in your documentation I get nothing relevant to these “quad” objects that I’m getting from Core.DocumentViewer.getPageSearchResults.

I would like to know if these are documented anywhere. If not, please explain what the type of these objects are and what their properties are. Or perhaps this object is meant to be opaque and getPoints is the single public API that we should just use if we need to? If that’s the case, having this actually documented would help to know that intent.

Please describe your issue and provide steps to reproduce it:
(The more descriptive your answer, the faster we are able to help you)
See above.

Please provide a link to a minimal sample where the issue is reproducible:
See above.

[darian.chen]

Hello James,

Text positions in WebViewer are represented by rectangles called quads, which have four sets of XY coordinates representing their corners. When text is split across multiple lines or columns, each section is represented by a quad object in an array.

Please refer to the following guide to learn more about text position and quads.

Apryse Documentation | Documentation

The Sx , Tx , Vx , Wx , ka , la , ma , and oa represent the 4 coordinates. You can see these points with x and y values by using the getPoints API like you mentioned. However, the object returned does not appear to be an instance of Core.Math.Quad, instead it simply an object with the same properties as a quad.

Best Regards,
Darian Chen

[jamesl]

Thanks for the reply @darian.chen. We use quads (with x1, y1, x2, y2, etc properties) for text positions heavily in our app already so getPoints is what we started to rely on from search results. My concern though mostly stems from these objects with Sx, Tx, etc not being documented, nor the getPoints method. Usually, when an API is not documented, we assume that they are private and may potentially change in the future without notice (rightfully so for private APIs).

But I guess what you’re telling me is that getPoints is meant to be public and it’s safe to call without worrying about having the rug pulled from under us?

[darian.chen]

Hello James,

Yes, the getPoints function is meant to be public and it is safe to call.

There is also another way to get the quad from text. You can use the getTextPosition API.
https://docs.apryse.com/api/web/Core.Document.html#getTextPosition

Please refer to the guide in my previous response to learn more.

Hope this helps.

Best Regards,
Darian Chen

[jamesl]

Thanks for confirming getPoints being a public API. As for getTextPosition I don’t think we’re able to actually use that for our particular use case, but I’ll definitely keep that in mind. Thanks for letting me know about that.

[brent.farese]

We are unable to call getPoints on a search result. getPoints is not a function/present on the SearchResult object that we are logging to the console. Below picture comes from the onResult callback of the textSearchInit method on DocumentViewer. There really needs to be a consistent, type-safe API here as this is causing runtime errors in our code.

How do we fix since it seems that getPoints is not reliable/a function on every SearchResult object.

[brent.farese]

It seems getPoints is on the quads object and not the SearchResult. The API should be documented and types available in TypeScript. Can Apryse add in future releases? Should be easy to add types…