Skip to content

Commit 418333d

Browse files
NeutreeNeutree
committed
bump version to v4.11.0
1 parent 6117f71 commit 418333d

File tree

4 files changed

+237
-125
lines changed

4 files changed

+237
-125
lines changed

‎docs/doc/en/vision/camera.md‎

Lines changed: 151 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -4,35 +4,53 @@ update:
44
- date: 2024-04-03
55
author: neucrack
66
version: 1.0.0
7-
content: Initial documentation
7+
content: Initial version of the document
8+
- date: 2024-08-21
9+
author: YWJ
10+
version: 1.0.1
11+
content: Fixed some bugs in the document, added some content
12+
- date: 2024-10-24
13+
author: neucrack
14+
version: 1.1.0
15+
content: Added USB camera support instructions
16+
- date: 2025-07-28
17+
author: neucrack & lxo
18+
version: 1.2.0
19+
content: Add AWB and lens usage doc.
820
---
921

1022
## Introduction
1123

12-
For the MaixCAM, it comes with a pre-installed GC4653 camera, or an optional OS04A10 camera or global shutter camera, and even an HDMI to MIPI module, all of which can be directly used with simple API calls.
24+
MaixCAM comes with a default GC4653 camera or optional OS04A10 camera, global shutter camera, or even HDMI to MIPI module, all of which can be used directly through simple API calls.
1325

1426
## API Documentation
1527

16-
This article introduces common methods. For more API usage, refer to the documentation of the [maix.camera](/api/maix/camera.html) module.
28+
This document introduces commonly used methods. For more API usage, please refer to the documentation of the [maix.camera](/api/maix/camera.html) module.
1729

1830
## Camera Switching
1931

2032
Currently supported cameras:
21-
* **GC4653**: M12 universal lens, 1/3" sensor, clear image quality, 4MP.
22-
* **OS04A10**: M12 universal lens, 1/1.8" large sensor, ultra-clear image quality, 4MP.
23-
* **OV2685**: Does not support lens replacement, lowest image quality, and lowest cost; generally not recommended for use.
24-
* **SC035HGS**: Monochrome global shutter camera, 0.3MP black-and-white, suitable for capturing high-speed objects.
2533

26-
The system will automatically switch; simply replace the hardware to use.
34+
* **GC4653**: M12 universal lens, 1/3" sensor, clear image quality, 4M pixels. Suitable for common scenarios such as AI recognition and image processing.
35+
* **OS04A10**: M12 universal lens, 1/1.8" large sensor, ultra-high image quality, 4M pixels. Suitable for scenarios that require high image quality, such as photography and video recording. Note that it generates more heat.
36+
* **OV2685**: Lens is not replaceable, 1/5" sensor, 2M pixels, lowest image quality and cost. Generally not recommended.
37+
* **SC035HGS**: Monochrome global shutter camera, 0.3M monochrome pixels, suitable for capturing fast-moving objects.
38+
39+
The system will switch automatically; just replace the hardware to use.
40+
41+
## Lens Cap
2742

28-
## Adjusting the Camera Focus
43+
The lens cap is for dust protection. **Please remove the lens cap!!** before use.
2944

30-
The MaixCAM comes with a manually adjustable focus lens by default. You can physically twist the lens to adjust the focal length.
31-
If the image appears blurry, try rotating the lens clockwise or counterclockwise to bring the image into clear focus.
45+
## Adjusting Camera Focus
3246

33-
## Getting Images from the Camera
47+
MaixCAM is equipped with a **manual focus lens** by default. You can physically rotate the lens to adjust focus.
48+
If you find the **image is blurry**, try rotating the lens (clockwise and counterclockwise) to focus until the image is clear.
49+
50+
## Getting Image from the Camera
51+
52+
Use MaixPy to easily acquire images:
3453

35-
Using MaixPy to easily get images:
3654
```python
3755
from maix import camera
3856

@@ -43,88 +61,135 @@ while 1:
4361
print(img)
4462
```
4563

46-
Here we import the `camera` module from the `maix` module, then create a `Camera` object, specifying the width and height of the image. Then, in a loop, we continuously read the images. The default output is in `RGB` format. If you need `BGR` format or other formats, please refer to the API documentation.
64+
Here we import the `camera` module from `maix`, create a `Camera` object with specified width and height, and then continuously read images in a loop. The default image format is `RGB`. For `BGR` or other formats, see the API documentation.
65+
66+
You can also get grayscale images:
4767

4868
```python
4969
from maix import camera, image
50-
cam = camera.Camera(640, 480, image.Format.FMT_GRAYSCALE) # Set the output greyscale image
70+
cam = camera.Camera(640, 480, image.Format.FMT_GRAYSCALE) # Set output to grayscale image
5171
```
52-
Also get the NV21 image
72+
73+
Or get NV21 images:
74+
5375
```python
5476
from maix import camera, image
55-
cam = camera.Camera(640, 480, image.Format.FMT_YVU420SP) # set to output NV21 image
77+
cam = camera.Camera(640, 480, image.Format.FMT_YVU420SP) # Set output to NV21 image
5678
```
5779

58-
Note: You need to disable MaixVision's online browsing function if you set a very high resolution (e.g. `2560x1440`), otherwise the code may run abnormally due to lack of memory.
59-
You can also get greyscale images
80+
## Set Camera Resolution
81+
82+
Specify width and height directly in the code:
83+
84+
```python
85+
from maix import camera
86+
cam = camera.Camera(width=640, height=480)
87+
```
88+
89+
or
90+
91+
```python
92+
from maix import camera
93+
cam = camera.Camera()
94+
cam.set_resolution(width=640, height=480)
95+
```
96+
97+
### Choosing Resolution Size
98+
99+
Different boards and camera modules support different resolutions. Make sure to use **even number values**.
100+
101+
It’s important to understand that **higher resolution is not always better**—choose the right resolution based on your scenario:
102+
103+
* Photography/Video/Monitoring: Higher resolution can give clearer images.
104+
GC4653 and OS04A10 support up to `2560x1440` resolution (i.e. `2K/4M pixels`). But high resolution demands more programming skill and memory. You may consider smaller resolutions such as `1920x1080`, `1280x720`, `640x480`, etc.
105+
Note: When running code in **MaixVision**, if you set high resolution (e.g., `2560x1440`), disable the image preview feature in MaixVision to avoid errors due to insufficient memory.
106+
* AI Recognition / Image Processing: For faster performance, reduce resolution as much as possible while still ensuring recognizability.
60107

61-
## Setting the frame rate of the camera
108+
* `640x480`: VGA resolution; large enough for most AI recognition and clear image processing. Demands more from MaixCAM; easier for MaixCAM2.
109+
* `320x320`: Square resolution; suitable for some AI models, but will have black borders on rectangle screens.
110+
* `320x240`: QVGA resolution; easy for algorithms, and still meets clarity needs.
111+
* `320x224`: Both width and height are multiples of 32; suitable for small resolution AI input and displays well on `552x368` screen.
112+
* `224x224`: Square, both dimensions are multiples of 32; fits small resolution AI models like `MobileNetV2`, `MobileNetV3`.
62113

63-
The GC4653 supports a maximum of three configurations: `2560x1440 30fps`, `1280x720 60fps`, and `1280x720 80fps`. The frame rate is selected based on the width, height, and fps parameters passed when creating the Camera object.
114+
### Aspect Ratio of Resolution
64115

65-
The OS04A10 supports a maximum of two configurations: `2560x1440 30fps` and `1280x720 80fps`. The `1280x720` resolution is achieved by center-cropping the `2560x1440` image.
116+
Aspect ratio affects field of view. For example, sensor max is `2560x1440` (16:9). Using `640x480` changes to 4:3, reducing field of view. To maximize view, choose resolution matching sensor's aspect ratio, e.g., `1280x720`, `2560x1440`.
66117

67-
### Setting the frame rate to 30 fps
118+
Different ratios will result in center cropping.
119+
120+
## Set Camera Frame Rate
121+
122+
The camera operates at specific frame rates. MaixPy supports frame rate settings. Supported frame rates vary by module:
123+
124+
| GC4653 | OS04A10 | OV2685 | SC035HGS |
125+
| ------------------------------------------------------ | ----------------------------------- | ---------------- | --------------- |
126+
| 2560x1440\@30fps<br>1280x720\@60fps<br>1280x720\@80fps | 2560x1440\@30fps<br>1280x720\@80fps | 1920x1080\@30fps | 640x480\@180fps |
127+
128+
Frame rate is set via `width`, `height`, and `fps` when creating `Camera`.
129+
130+
### Set Frame Rate to 30fps
68131

69132
```python
70133
from maix import camera
71-
cam = camera.Camera(640, 480, fps=30) # set the frame rate to 30 fps
134+
cam = camera.Camera(640, 480, fps=30)
72135
# or
73-
cam = camera.Camera(1920, 1280) # Frame rate is set to 30 fps when resolution is higher than 1280x720
136+
cam = camera.Camera(1920, 1280) # Above 1280x720 will auto use 30fps
74137
```
75138

76-
### Set the frame rate to 60 fps
139+
### Set Frame Rate to 60fps
77140

78141
```python
79142
from maix import camera
80-
cam = camera.Camera(640, 480, fps=60) # Set frame rate to 60 fps
143+
cam = camera.Camera(640, 480, fps=60)
81144
# or
82-
cam = camera.Camera(640, 480) # Set frame rate to 60fps if resolution is less than or equal to 1280x720
145+
cam = camera.Camera(640, 480) # ≤1280x720 defaults to 80fps
83146
```
84147

85-
### Set the frame rate to 80 fps
148+
### Set Frame Rate to 80fps
86149

87150
```python
88151
from maix import camera
89-
cam = camera.Camera(640, 480, fps=80) # Set frame rate to 60 fps
152+
cam = camera.Camera(640, 480, fps=80)
90153
```
91154

92155
Notes:
93156

94-
1. if `Camera` is passed in a size larger than `1280x720`, for example written as `camera.Camera(1920, 1080, fps=60)`, then the `fps` parameter will be invalidated, and the frame rate will remain at `30fps`.
95-
2. A `60/80fps` frame will be offset by a few pixels compared to a `30fps` frame, and the offset will need to be corrected if the viewing angle is critical.
96-
3. Note that due to the fact that `60/80fps` and `30fps` share the same `isp` configuration, in some environments there will be some deviation in the quality of the screen at the two frame rates.
97-
4. The camera's performance depends on the system. Some systems may not support setting the camera to 80fps, which can result in strange patterns appearing on the screen. In such cases, please switch back to the normal 60fps setting.
157+
1. If size > `1280x720`, e.g., `camera.Camera(1920, 1080, fps=60)`, then `fps` param is ignored and stays at 30fps.
158+
2. 60/80fps images may shift by a few pixels compared to 30fps—consider correcting this if precise alignment is needed.
159+
3. 60/80fps and 30fps share ISP config—image quality may vary slightly.
160+
4. Some camera setups can't handle 80fps—may show visual artifacts. Switch back to 60fps if needed.
98161

99-
## Image correction
162+
## Image Correction
100163

101-
In case of distortion such as fisheye, you can use the `lens_corr` function under the `Image` object to correct the distortion of the image. In general, you just need to increase or decrease the value of `strength` to adjust the image to the right effect.
164+
For fisheye or distortion, use `lens_corr` under `Image` to correct. Adjust the `strength` value for best results.
102165

103-
``python
104-
from maix import camera, display
166+
```python
167+
from maix import camera, display, app, time
105168

106169
cam = camera.Camera(320, 240)
107170
disp = display.Display()
108-
while not app.need_exit():: t = time.
171+
while not app.need_exit():
109172
t = time.ticks_ms()
110-
img = cam.read()
111-
img = img.lens_corr(strength=1.5) # Adjust the strength value until the image is no longer distorted.
112-
disp = display.Display()
113-
``
173+
img = cam.read()
174+
img = img.lens_corr(strength=1.5) # Adjust strength until distortion is gone
175+
disp.show(img)
176+
```
177+
178+
Note: This is software-based correction and consumes time. You may also use non-distorted lenses (ask vendor).
114179

115-
Note that since the correction is done through software, it takes some time. Alternatively, you can use a distortion-free lens (inquire with the vendor) to solve the issue from a hardware perspective.
180+
## Skip Initial Frames
116181

117-
## Skipping Initial Frames
182+
During initialization, camera may output unstable images. Skip first few frames using `skip_frames`:
118183

119-
During the brief initialization period of the camera, the image acquisition may not be stable, resulting in strange images. You can use the `skip_frames` function to skip the initial few frames:
120184
```python
121185
cam = camera.Camera(640, 480)
122-
cam.skip_frames(30) # Skip the first 30 frames
186+
cam.skip_frames(30) # Skip first 30 frames
123187
```
124188

125-
## Displaying Images
189+
## Display Camera Image
190+
191+
MaixPy provides the `display` module for easy image display:
126192

127-
MaixPy provides the `display` module, which can conveniently display images:
128193
```python
129194
from maix import camera, display
130195

@@ -136,57 +201,61 @@ while 1:
136201
disp.show(img)
137202
```
138203

139-
## Setting the camera parameters
204+
## Set Camera Parameters
140205

141-
### Set exposure time
206+
### Set Exposure Time
142207

143-
Note that after setting the exposure time, the camera will switch to manual exposure mode, if you want to switch back to automatic exposure mode you need to run `cam.exp_mode(camera.AeMode.Auto)`.
208+
Note: Setting exposure time switches to manual exposure. To revert to auto mode, run `cam.exp_mode(camera.AeMode.Auto)`
144209

145210
```python
146211
from maix import camera
147212
cam = camera.Camera()
148213
cam.exposure(1000)
149214
```
150215

151-
### Setting the gain
216+
### Set Gain
152217

153-
Note that after setting the gain, the camera will switch to manual exposure mode, to switch back to auto exposure mode you need to run `cam.exp_mode(camera.AeMode.Auto)`. Customised gain values will only work in manual exposure mode.
218+
Note: Setting gain switches to manual exposure. Custom gain only works in manual mode.
154219

155220
```python
156221
from maix import camera
157222
cam = camera.Camera()
158223
cam.gain(100)
159224
```
160225

161-
### Setting the white balance
162-
Currently, only manual white balance via gain adjustment is supported. Use set_wb_gain() to pass in an array of four values corresponding to the gain for `R`, `Gr`, `Gb`, and `B` channels, with each value ranging from [0.0, 1.0].
226+
### Set White Balance
227+
228+
Usually auto white balance suffices. For color-sensitive scenarios, manually set it:
229+
230+
Set `awb_mode` to `Manual`, then set gain for `R`, `Gr`, `Gb`, `B` channels. Range: `[0.0, 1.0]`.
163231

164-
The recommended default manual white balance gains are:
165-
For MaixCam: [0.134, 0.0625, 0.0625, 0.1239]
166-
For MaixCam2: [0.0682, 0, 0, 0.04897]
167-
To fine-tune image appearance, it is usually sufficient to adjust only the `R` and `B` channels, while keeping `Gr` and `Gb` unchanged.
232+
Default gain values:
233+
234+
* `MaixCAM`: `[0.134, 0.0625, 0.0625, 0.1239]`
235+
* `MaixCAM2`: `[0.0682, 0, 0, 0.04897]`
236+
237+
Usually only `R` and `B` need adjustment.
168238

169239
```python
170240
from maix import camera
171241
cam = camera.Camera()
172-
cam.awb_mode(camera.AwbMode.Manual) # AwbMode.Manual to enable auto white balance, AwbMode.Manual to enable manual white balance
173-
cam.set_wb_gain([0.134, 0.0625, 0.0625, 0.1239]) # Set gains for R, Gr, Gb, B channels
174-
242+
cam.awb_mode(camera.AwbMode.Manual)
243+
cam.set_wb_gain([0.134, 0.0625, 0.0625, 0.1239])
175244
```
176245

177-
### Setting brightness, contrast and saturation
246+
### Set Brightness, Contrast, Saturation
178247

179248
```python
180249
from maix import camera
181250
cam = camera.Camera()
182-
cam.luma(50) # Set brightness, range [0, 100]
183-
cam.constrast(50) # set contrast, range [0, 100]
184-
cam.saturation(50) # Set the saturation, range [0, 100].
251+
cam.luma(50) # Brightness [0, 100]
252+
cam.constrast(50) # Contrast [0, 100]
253+
cam.saturation(50) # Saturation [0, 100]
185254
```
186255

187-
### Reading Raw Images
256+
### Read Raw Image
188257

189-
Note that the output `raw` image is the original `Bayer` image, and the format of the `Bayer` image may vary depending on the camera module.
258+
To read raw `bayer` image data for processing or debugging:
190259

191260
```python
192261
from maix import camera
@@ -195,39 +264,24 @@ raw_img = cam.read_raw()
195264
print(raw_img)
196265
```
197266

198-
If you need to open the `raw` image in third-party software, additional conversion on the PC side is required. You can refer to the example code in [bayer_to_tiff](https://github.com/sipeed/MaixPy/blob/dev/examples/tools/bayer_to_tiff.py).
267+
For viewing on PC, use script like [bayer\_to\_tiff](https://github.com/sipeed/MaixPy/blob/dev/examples/tools/bayer_to_tiff.py).
199268

269+
## Change Lens
200270

271+
MaixCAM uses M12 lens by default and supports lens replacement. Notes:
201272

202-
## Using a USB Camera
273+
1. Ensure new lens is M12.
274+
2. Different lenses have different flange back distances. Default lens mount has fixed height—check compatibility.
275+
3. Avoid scratching sensor surface. Blow dust gently, clean with lens paper only if necessary.
276+
4. Want a zoom lens? Buy M12 zoom lens.
277+
5. Default is manual focus. Auto-focus lenses require driver support; MaixCAM lacks AF circuit—you may need to write control program.
203278

204-
In addition to using the MIPI interface camera that comes with the development board, you can also use an external USB camera.
205-
Method:
206-
* First, in the development board settings, select `USB Mode` under `USB Settings` and set it to `HOST` mode. If there is no screen available, you can use the `examples/tools/maixcam_switch_usb_mode.py` script to set it.
207-
* Currently (as of 2024.10.24), the `maix.camera` module does not yet support USB cameras, but you can use `OpenCV` for this.
279+
## Use USB Camera
208280

209-
```python
210-
from maix import image, display
211-
import cv2
212-
import sys
213-
214-
cap = cv2.VideoCapture(0)
215-
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)
216-
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)
217-
# cap.set(cv2.CAP_PROP_CONVERT_RGB, 0)
281+
Besides built-in MIPI camera, you can use USB camera.
218282

219-
disp = display.Display()
283+
Steps:
220284

221-
if not cap.isOpened():
222-
print("Unable to open camera")
223-
sys.exit(1)
224-
print("Starting to read")
225-
while True:
226-
ret, frame = cap.read()
227-
if not ret:
228-
print("Unable to read frame")
229-
return
230-
img = image.cv2image(frame, bgr=True, copy=False)
231-
disp.show(img)
232-
```
285+
* Set `USB Mode` to `HOST` in system settings. Without screen, use script `examples/tools/maixcam_switch_usb_mode.py`.
286+
* As of 2024.10.24, `maix.camera` module **does not** support USB camera. Refer to [Using USB Camera with OpenCV](./opencv.md).
233287

0 commit comments

Comments
 (0)