diff --git a/text.bs b/text.bs index 5499444..1b86483 100644 --- a/text.bs +++ b/text.bs @@ -42,7 +42,10 @@ Please see the -Example implementations of Text code detection are e.g. Google Play Services, Apple's CIDetector (bounding box only, no OCR) or Windows 10 OCR API. - + +dictionary TextDetectorOptions { + required sequence<DOMString> languages; +}; + +dictionary TextDetectorCreateOptions { + AbortSignal signal; + sequence<DOMString> languages; +}; + [ Exposed=(Window,Worker), SecureContext ] interface TextDetector { constructor(); + static Promise<Availability> availability(TextDetectorOptions options); + static Promise<TextDetector> create(optional TextDetectorCreateOptions options = {}); Promise<sequence<DetectedText>> detect(ImageBitmapSource image); }; @@ -73,10 +85,51 @@ Example implementations of Text code detection are e.g. availability(TextDetectorOptions |options|) +
+

+ Returns a {{Promise}} that resolves with an {{Availability}} object + indicating the overall availability status for the specified |options| languages for text + detection. +

+

+ The returned {{Availability}} value is determined by the following precedence, + applied across all requested languages: +

+ +
+ This method allows developers to check for specific language support before + attempting to create a {{TextDetector}} instance. +
+
+
create(optional TextDetectorCreateOptions |options|)
+
+

+ Returns a {{Promise}} that resolves with a new {{TextDetector}} + instance. +

+
+ This factory method handles the asynchronous initialization of the + text detector, including downloading necessary resources. It is recommended + to use this asynchronous method over the synchronous constructor + to accommodate potential delays from dependency downloads or initialization, + ensuring a smoother user experience. +
+
detect(ImageBitmapSource |image|)
Tries to detect text blocks in the {{ImageBitmapSource}} |image|.
+ ### {{DetectedText}} ### {#detectedtext-section} @@ -102,49 +155,66 @@ dictionary DetectedText { <i>This section is non-normative.</i> -<p class="note"> -Slightly modified/extended versions of these examples (and more) can be found in - e.g. <a href="https://codepen.io/collection/DwWVJj/">this codepen collection</a>. -</p> -## Platform support for a text detector ## {#example-feature-detection} -<div class="note"> -The following example can also be found in e.g. <a -href="https://codepen.io/miguelao/pen/PbYpMv?editors=0010">this codepen</a> -with minimal modifications. -</div> +## Platform support for a text detector ## {#example-feature-detection} <div class="example"> ```js -if (window.TextDetector == undefined) { +if (!('TextDetector' in window)) { console.error('Text Detection not supported on this platform'); +} else { + const languages = ['en', 'es']; // English and Spanish + TextDetector.availability({ languages: languages }).then(availability => { + if (availability === 'unavailable') { + console.log('Not all of the requested languages are supported.'); + return; + } + + if (availability === 'downloadable') { + console.log('Languages need to be downloaded first.'); + } else if (availability === 'downloading') { + console.log('Languages are currently being downloaded.'); + } else { + console.log('All requested languages are supported.'); + } + + // Now you can create a TextDetector with the supported languages. + // If the status was 'downloadable' or 'downloading', create() will wait + // for the download to finish before resolving. + TextDetector.create({ languages: languages }).then(detector => { + // ... use the detector + }); + }); } ``` </div> ## Text Detection ## {#example-text-detection} -<div class="note"> -The following example can also be found in e.g. -<a href="https://codepen.io/miguelao/pen/ygxVqg">this codepen</a>. -</div> + <div class="example"> ```js -let textDetector = new TextDetector(); -// Assuming |theImage| is e.g. a &lt;img> content, or a Blob. - -textDetector.detect(theImage) -.then(detectedTextBlocks => { - for (const textBlock of detectedTextBlocks) { - console.log( - 'text @ (${textBlock.boundingBox.x}, ${textBlock.boundingBox.y}), ' + - 'size ${textBlock.boundingBox.width}x${textBlock.boundingBox.height}'); +(async () => { + // Assuming |theImage| is e.g. a <img> content, or a Blob. + try { + // The legacy synchronous constructor is still supported, + // but the async create() method is recommended. + // let textDetector = new TextDetector(); + + let textDetector = await TextDetector.create(); + + const detectedTextBlocks = await textDetector.detect(theImage); + for (const textBlock of detectedTextBlocks) { + console.log( + `text @ (${textBlock.boundingBox.x}, ${textBlock.boundingBox.y}), ` + + `size ${textBlock.boundingBox.width}x${textBlock.boundingBox.height}`); + } + } catch (e) { + console.error("Text Detection failed, boo.", e); } -}).catch(() => { - console.error("Text Detection failed, boo."); -}) +})(); ``` </div> @@ -154,6 +224,9 @@ spec: html text: allowed to show a popup text: in parallel text: incumbent settings object +spec: writing-assistance-apis + type: enum + text: Availability </pre> <pre class="biblio">