Skip to content

Commit 4382562

Browse files
DMGithubPublisherDMGithubPublisher
committed
update to internal commit f4c8d7a9
1 parent 7f03914 commit 4382562

File tree

6 files changed

+464
-61
lines changed

6 files changed

+464
-61
lines changed

‎_config.yml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@ dnt_icon: /camera-enhancer/docs/web/assets/img-icon/icon-dnt.svg
4545
overview: /camera-enhancer/overview/
4646
download: /camera-enhancer/downloads/
4747

48-
useVersionTree: true
48+
useVersionTree: false
49+
isDCV: true
4950

5051
baseurl: "/camera-enhancer/docs/web/"
5152
plugins:

‎_layouts/default-layout.html renamed to ‎_layouts/default-layout-OLD.html

File renamed without changes.

‎_layouts/search-page.html renamed to ‎_layouts/search-page-OLD.html

File renamed without changes.

‎programming/javascript/user-guide/index-v4.0.3.md

Lines changed: 375 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,375 @@
1+
---
2+
layout: default-layout
3+
title: User Guide - Dynamsoft Camera Enhancer for JavaScript
4+
description: This is the user guide of Dynamsoft Camera Enhancer JavaScript SDK.
5+
keywords: user guide, javascript, js
6+
breadcrumbText: User Guide
7+
noTitleIndex: true
8+
needGenerateH3Content: true
9+
needAutoGenerateSidebar: true
10+
---
11+
12+
# Dynamsoft Camera Enhancer for Your Website
13+
14+
Dynamsoft Camera Enhancer allows your website to easily control the camera in the browser on desktop or mobile devices.
15+
16+
With the SDK integrated, your users can open your website in a browser, access their cameras to stream live video and acquire real-time frames for further processing. The SDK also supports simple shape drawing, allowing information to be presented directly on the video stream or over a static image for integrated user interaction.
17+
18+
In this guide, you will learn step by step on how to integrate the Dynamsoft Camera Enhancer SDK into your website.
19+
20+
- [Dynamsoft Camera Enhancer for Your Website](#dynamsoft-camera-enhancer-for-your-website)
21+
- [Adding the SDK](#adding-the-sdk)
22+
- [Use a CDN](#use-a-cdn)
23+
- [Host the SDK yourself](#host-the-sdk-yourself)
24+
- [Using the SDK](#using-the-sdk)
25+
- [Stream live video](#stream-live-video)
26+
- [Capture image frames](#capture-image-frames)
27+
- [Use ImageEditorView](#use-imageeditorview)
28+
- [Customize the UI](#customize-the-ui)
29+
- [Hosting the SDK](#hosting-the-sdk)
30+
- [Step One: Deploy the dist folder](#step-one-deploy-the-dist-folder)
31+
- [Step Two: Configure the Server](#step-two-configure-the-server)
32+
- [Step Three: Add the SDK from the server](#step-three-add-the-sdk-from-the-server)
33+
- [FAQ](#faq)
34+
- [Can I open the web page directly from the hard drive?](#can-i-open-the-web-page-directly-from-the-hard-drive)
35+
- [Why can't I use my camera?](#why-cant-i-use-my-camera)
36+
- [API Documentation](#api-documentation)
37+
- [System Requirements](#system-requirements)
38+
- [Release Notes](#release-notes)
39+
- [Next Steps](#next-steps)
40+
41+
## Adding the SDK
42+
43+
To use the SDK, we first add the following packages:
44+
45+
1. `dynamsoft-camera-enhancer`: Required, it provides the camera related functionalities used in this guide.
46+
2. `dynamsoft-core`: Required, it includes basic classes, interfaces, and enumerations that are shared between all Dynamsoft SDKs.
47+
3. `dynamsoft-license`: Optional, if you wish to utilize advanced features such as auto-zoom, enhanced focus, and tap-to-focus, you will need it.
48+
49+
### Use a CDN
50+
51+
The simplest way to add the SDK is to use a CDN such as [jsDelivr](https://jsdelivr.com/) or [UNPKG](https://unpkg.com/).
52+
53+
- jsDelivr
54+
55+
```html
56+
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-core@3.2.30/dist/core.js"></script>
57+
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-license@3.2.21/dist/license.js"></script>
58+
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@4.0.3/dist/dce.js"></script>
59+
```
60+
61+
- UNPKG
62+
63+
```html
64+
<script src="https://unpkg.com/dynamsoft-core@3.2.30/dist/core.js"></script>
65+
<script src="https://unpkg.com/dynamsoft-license@3.2.21/dist/license.js"></script>
66+
<script src="https://unpkg.com/dynamsoft-camera-enhancer@4.0.3/dist/dce.js"></script>
67+
```
68+
69+
> In some rare cases, you might not be able to access the CDN. If this happens, you can use
70+
>- [https://download2.dynamsoft.com/packages/dynamsoft-core@3.2.30/dist/core.js](https://download2.dynamsoft.com/packages/dynamsoft-core@3.2.10/dist/core.js)
71+
>- [https://download2.dynamsoft.com/packages/dynamsoft-license@3.2.21/dist/license.js](https://download2.dynamsoft.com/packages/dynamsoft-license@3.2.10/dist/license.js)
72+
>- [https://download2.dynamsoft.com/packages/dynamsoft-camera-enhancer@4.0.3/dist/dce.js](https://download2.dynamsoft.com/packages/dynamsoft-camera-enhancer@4.0.2/dist/dce.js)
73+
74+
### Host the SDK yourself
75+
76+
Besides using the CDN, you can also download the SDK and host it locally.
77+
78+
The following shows a few ways to download the SDK.
79+
80+
- yarn
81+
82+
```cmd
83+
yarn add dynamsoft-camera-enhancer
84+
```
85+
86+
- npm
87+
88+
```cmd
89+
npm install dynamsoft-camera-enhancer --save
90+
```
91+
92+
> Note: Upon installation of `dynamsoft-camera-enhancer`, a compatible versions of `dynamsoft-core` will be automatically installed if not installed already.
93+
94+
Depending on how you downloaded the SDK and where you put it. You can typically add it like this:
95+
96+
```html
97+
<script src="./node_modules/dynamsoft-core/dist/core.js"></script>
98+
<script src="./node_modules/dynamsoft-camera-enhancer/dist/dce.js"></script>
99+
```
100+
101+
Read more on [how to host the SDK](#hosting-the-sdk).
102+
103+
## Using the SDK
104+
105+
### Stream live video
106+
107+
We can create a `CameraEnhancer` instance to open and show the video stream on the page. The following code snippet demonstrates the complete process:
108+
109+
1. Create a `CameraView` instance. In our case, it's named `cameraView`;
110+
2. Pass `cameraView` to the method `createInstance()` to create a `CameraEnhancer` instance. This way, `cameraView` is bound to the created object `cameraEnhancer`;
111+
3. Show the UI element of `cameraView` by appending it to an existing element in the DOM;
112+
4. Open the video stream which will show up in the UI Element.
113+
114+
```html
115+
<!-- Define an element to hold the UI element -->
116+
<div id="enhancerUIContainer" style="width:1280px;height:720px;"></div>
117+
<script>
118+
(async () => {
119+
// Initializes the license for using the SDK in the application.
120+
Dynamsoft.License.LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9");
121+
// A default UI will be used if no parameter is passed to 'CameraView.createInstance()'.
122+
let cameraView = await Dynamsoft.DCE.CameraView.createInstance();
123+
// Create 'CameraEnhancer' instance and pass 'cameraView' to it.
124+
let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView);
125+
// Get 'CameraView' instance's UI and append it to DOM.
126+
document.querySelector("#enhancerUIContainer").append(cameraView.getUIElement());
127+
// Open the camera and start streaming the video on the page.
128+
await cameraEnhancer.open();
129+
})();
130+
</script>
131+
```
132+
133+
### Capture image frames
134+
135+
There are two ways to capture image frames with Dynamsoft Camera Enhancer.
136+
137+
- Capture a single latest frame
138+
139+
This is done with the method [fetchImage()](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/api-reference/acquisition.html#fetchimage) as shown in the following code snippet:
140+
141+
```javascript
142+
let img = cameraEnhancer.fetchImage();
143+
document.body.appendChild(img.toCanvas());
144+
```
145+
146+
- Start a capture loop that captures multiple frames at a steady interval into a buffer and then read frames from the buffer. The following code snippet shows how it works:
147+
148+
```javascript
149+
// Capture an image frame every 2 seconds and subsequently append it to the buffer.
150+
cameraEnhancer.setImageFetchInterval(2000);
151+
// The event "frameAddedToBuffer" is triggered whenever a new frame is added to the buffer.
152+
cameraEnhancer.on("frameAddedToBuffer", () => {
153+
let img = cameraEnhancer.getImage();
154+
console.log(img);
155+
});
156+
// Start the built-in fetching loop.
157+
cameraEnhancer.startFetching();
158+
```
159+
160+
### Use ImageEditorView
161+
162+
The other view class ImageEditorView is designed to show a single image. The following code snippet shows a single frame in an `ImageEditorView` instance and draws a rectangle on the image:
163+
164+
```html
165+
<div id="imageEditorContainer" style="width:1280px;height:720px;"></div>
166+
```
167+
168+
```javascript
169+
// The default UI will be used if no parameter is provided to 'ImageEditorView.createInstance()'.
170+
let editorView = await Dynamsoft.DCE.ImageEditorView.createInstance();
171+
// Retrieve the UI of the 'editorView' instance and append it to the DOM.
172+
document.querySelector("#imageEditorContainer").append(editorView.getUIElement());
173+
// When the video is already playing, capture an image and draw it on the ImageEditorView.
174+
let img = cameraEnhancer.fetchImage();
175+
editorView.setOriginalImage(img);
176+
// Draw a rectangle on the image.
177+
let drawingLayer = editorView.createDrawingLayer();
178+
let rect = new Dynamsoft.DCE.RectDrawingItem(
179+
{
180+
x: 100,
181+
y: 100,
182+
width: 1070,
183+
height: 520
184+
});
185+
drawingLayer.addDrawingItems([rect]);
186+
```
187+
188+
Once the rectangle appears on the image, you can click to select it and adjust its position, size, etc.
189+
190+
Read more about [How to draw shapes](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/user-guide/features/draw-shapes.html).
191+
192+
### Customize the UI
193+
194+
Dynamsoft Camera Enhancer (DCE) offers extensive customization options. If you only need to adjust the UI without delving into other features, this section is for you.
195+
196+
**Use the built-in UI**
197+
198+
DCE includes several pre-defined UIs in the `DCE-LIB-PACKAGE/dist/xxxx.ui.html`.
199+
200+
* `dce.ui.html`: The default UI used by CameraView.createInstance() for simple use cases.
201+
* `dce.mobile-native.ui.html`: A mobile-inspired UI with auto flash, suitable for most websites. Activate it with `CameraView.createInstance('@engineResourcePath/dce.mobile-native.ui.html')`.
202+
203+
When `cameraEnhancer.open()` is called, the UI elements are dynamically bound to functions based on their class names, such as `dce-xxxx`.
204+
205+
**Modify the UI dynamically**
206+
207+
To customize the UI, call `view.getUIElement()` to access the HTMLElement containing all UI elements. Before `cameraEnhancer.open()`, you can modify the UI by editing CSS, adding/removing elements, or restructuring the HTML. This usually works without issues, though testing is recommended.
208+
209+
After `cameraEnhancer.open()`, UI adjustments are possible via JavaScript, but handle elements with `dce-` prefixed class names carefully, as they may be linked to specific logic.
210+
211+
**Define the UI in a separate HTML**
212+
213+
For less dynamic but more structured customization, create a copy of the desired `xxxx.ui.html`, modify it as needed, and store it in your project's `public` folder. Use this customized UI with `CameraView.createInstance('PATH-TO/xxxx.ui.html')`.
214+
215+
**Integrate HTML into Your Project**
216+
217+
Alternatively, `CameraView.createInstance()` accepts an `HTMLElement` directly. This allows you to build and manage the UI within your webpage. For example, set the UI using `CameraView.createInstance(document.getElementById('my-custom-ui'))`.
218+
219+
Let's see the following example.
220+
221+
**Practise: customize base on `dce.ui.html`**
222+
223+
Start by opening dce.ui.html in your editor to review its content. You can copy several elements from this file.
224+
225+
Next, create a new HTML page, beginning by embedding only the video:
226+
227+
```html
228+
<div id="enhancerUIContainer" style="width:1280px;height:720px;background:#ddd;" >
229+
<div class="dce-video-container" style="width:100%;height:100%;"></div>
230+
</div>
231+
<script>
232+
(async () => {
233+
// Initializes the license for using the SDK in the application.
234+
Dynamsoft.License.LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9");
235+
// Create 'CameraView' instance and pass the element "enhancerUIContainer" as its UI.
236+
let cameraView = await Dynamsoft.DCE.CameraView.createInstance(document.getElementById("enhancerUIContainer"));
237+
let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView);
238+
await cameraEnhancer.open();
239+
})();
240+
</script>
241+
```
242+
243+
> The video element will automatically be created and appended to the `dce-video-container` div.
244+
245+
Next, add the camera and resolution list. If the classes match the default ones (`dce-sel-camera` and `dce-sel-resolution`), the SDK will populate them and manage switching.
246+
247+
```html
248+
<div id="enhancerUIContainer" style="position:relative;width:1280px;height:720px;background:#ddd;" >
249+
<div class="dce-video-container" style="width:100%;height:100%;"></div>
250+
<div style="position: absolute;left: 0;top: 0;">
251+
<select class="dce-sel-camera" style="display: block;"></select>
252+
</div>
253+
</div>
254+
```
255+
256+
```html
257+
<div id="enhancerUIContainer" style="position:relative;width:1280px;height:720px;background:#ddd;" >
258+
<div class="dce-video-container" style="width:100%;height:100%;"></div>
259+
<div style="position:absolute;left:0;top:0;">
260+
<select class="dce-sel-camera" style="display:block;"></select>
261+
<select class="dce-sel-resolution" style="display:block;margin-top:5px;"></select>
262+
</div>
263+
</div>
264+
```
265+
266+
> By default, only 3 hard-coded resolutions (1920 x 1080, 1280 x 720, 640 x 480) are available. You can show a customized set of options by hardcoding them.
267+
268+
```html
269+
<select class="dce-sel-resolution">
270+
<option class="dce-opt-gotResolution" value="got"></option>
271+
<option data-width="1920" data-height="1080">1920x1080</option>
272+
<option data-width="1280" data-height="720">1280x720</option>
273+
<option data-width="640" data-height="480">640x480</option>
274+
</select>
275+
```
276+
277+
> Ensure the selected resolution is supported by the camera. If not, the closest supported resolution will be used. The `dce-opt-gotResolution` class shows the **actual resolution**.
278+
279+
**End of the section: customize the UI**
280+
281+
This concludes the UI customization section. Whether using built-in UIs or custom HTML, the process is straightforward.
282+
283+
## Hosting the SDK
284+
285+
### Step One: Deploy the dist folder
286+
287+
Once you have downloaded the SDK, you can locate the "dist" directory and copy it to your project (usually as part of your website / web application). The following shows some of the files in this directory:
288+
289+
- `dce.js` // The main SDK file
290+
- `dce.mjs` // For using the SDK as a module (`<script type="module">`)
291+
- `dce.ui.html` // Defines the default cameraEnhancer UI
292+
293+
### Step Two: Configure the Server
294+
295+
- Enable HTTPS
296+
297+
To use the SDK, you must access your website / web application via a secure HTTPS connection. This is due to browser security restrictions which only grant camera video streaming access to a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts).
298+
299+
> For convenience, self-signed certificates can be used during development and testing. You can also use "http://localhost" which allows camera access without an SSL certificate.
300+
301+
### Step Three: Add the SDK from the server
302+
303+
Now that the SDK is hosted on your server, you can add it accordingly.
304+
305+
```html
306+
<script src="https://www.yourwebsite.com/PATH-TO-THE-SDK/dynamsoft-camera-enhancer/dist/dce.js"></script>
307+
```
308+
309+
## FAQ
310+
311+
### Can I open the web page directly from the hard drive?
312+
313+
Yes, for simple testing purposes, it's ok to open the file directly from the hard drive (`file://`). However, you might encounter some issues in doing so (cannot access camera, etc.). The recommendation is to deploy this page to your web server and run it over **HTTPS** or use "http://localhost" during development.
314+
315+
If you don't have a ready-to-use web server but have a package manager like *npm* or *yarn*, you can set up a simple HTTP server in minutes. Check out [`http-server` on npm](https://www.npmjs.com/package/http-server) or [`http-server` on yarn](https://yarnpkg.com/package/http-server).
316+
317+
### Why can't I use my camera?
318+
319+
If you open the web page as `http://` , the camera may not work and you see a warnings or an error in the browser console. This is usually because the API [getUserMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) requires HTTPS to access the camera.
320+
321+
To make sure your web application can access the camera, please configure your web server to support HTTPS. The following links may help.
322+
323+
- NGINX: [Configuring HTTPS servers](https://nginx.org/en/docs/http/configuring_https_servers.html)
324+
- IIS: [Create a Self Signed Certificate in IIS](https://aboutssl.org/how-to-create-a-self-signed-certificate-in-iis/)
325+
- Tomcat: [Setting Up SSL on Tomcat in 5 minutes](https://dzone.com/articles/setting-ssl-tomcat-5-minutes)
326+
- Node.js: [npm tls](https://nodejs.org/docs/v0.4.1/api/tls.html)
327+
328+
## API Documentation
329+
330+
You can check out the detailed documentation about the APIs of the SDK at
331+
[https://www.dynamsoft.com/camera-enhancer/docs/programming/javascript/api-reference/index.html](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/api-reference/index.html).
332+
333+
## System Requirements
334+
335+
DCE requires the following features to work:
336+
337+
* Secure context (HTTPS deployment)
338+
339+
When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons
340+
341+
* Access to the camera video stream is only granted in a security context. Most browsers impose this restriction.
342+
> Some browsers like Chrome may grant the access for `http://127.0.0.1` and `http://localhost` or even for pages opened directly from the local disk (`file:///...`). This can be helpful for temporary development and test.
343+
344+
* Dynamsoft License requires a secure context to work.
345+
346+
* `MediaDevices`/`getUserMedia`
347+
348+
This API is only required for in-browser video streaming.
349+
350+
* `getSettings`
351+
352+
This API inspects the video input which is a `MediaStreamTrack` object about its constrainable properties.
353+
354+
The following table is a list of supported browsers based on the above requirements:
355+
356+
| Browser Name | Version |
357+
| :----------: | :-----: |
358+
| Chrome | v59+ |
359+
| Firefox | v63+ |
360+
| Edge | v79+ |
361+
| Safari | v11+ |
362+
363+
Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK. Browser compatibility ultimately depends on whether the browser on that particular operating system supports the features listed above.
364+
365+
## Release Notes
366+
367+
Learn about what are included in each release at [https://www.dynamsoft.com/camera-enhancer/docs/programming/javascript/release-note/index.html](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/release-note/index.html).
368+
369+
## Next Steps
370+
371+
Now that you have got the SDK integrated, you can choose to move forward in the following directions
372+
373+
1. Check out the [official samples on Github](https://github.com/Dynamsoft/camera-enhancer-javascript-samples).
374+
2. Learn about the available [APIs](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/api-reference/index.html).
375+
3. Learn more about the [Shape Drawing Feature](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/user-guide/features/draw-shapes.html).

0 commit comments

Comments
 (0)