summaryrefslogtreecommitdiff
path: root/src/py/examples/simple-cam.py
blob: 1cd1019da9558fa19d72c2d6d91560d45da2ae8a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
#!/usr/bin/env python3

# SPDX-License-Identifier: BSD-3-Clause
# Copyright (C) 2022, Tomi Valkeinen <tomi.valkeinen@ideasonboard.com>

# A simple libcamera capture example
#
# This is a python version of simple-cam from:
# https://git.libcamera.org/libcamera/simple-cam.git
#
# \todo Move to simple-cam repository when the Python API has stabilized more

import libcamera as libcam
import selectors
import sys
import time

TIMEOUT_SEC = 3


def handle_camera_event(cm):
    # cm.get_ready_requests() returns the ready requests, which in our case
    # should almost always return a single Request, but in some cases there
    # could be multiple or none.

    reqs = cm.get_ready_requests()

    # Process the captured frames

    for req in reqs:
        process_request(req)


def process_request(request):
    global camera

    print()

    print(f'Request completed: {request}')

    # When a request has completed, it is populated with a metadata control
    # list that allows an application to determine various properties of
    # the completed request. This can include the timestamp of the Sensor
    # capture, or its gain and exposure values, or properties from the IPA
    # such as the state of the 3A algorithms.
    #
    # To examine each request, print all the metadata for inspection. A custom
    # application can parse each of these items and process them according to
    # its needs.

    requestMetadata = request.metadata
    for id, value in requestMetadata.items():
        print(f'\t{id.name} = {value}')

    # Each buffer has its own FrameMetadata to describe its state, or the
    # usage of each buffer. While in our simple capture we only provide one
    # buffer per request, a request can have a buffer for each stream that
    # is established when configuring the camera.
    #
    # This allows a viewfinder and a still image to be processed at the
    # same time, or to allow obtaining the RAW capture buffer from the
    # sensor along with the image as processed by the ISP.

    buffers = request.buffers
    for _, buffer in buffers.items():
        metadata = buffer.metadata

        # Print some information about the buffer which has completed.
        print(f' seq: {metadata.sequence:06} timestamp: {metadata.timestamp} bytesused: ' +
              '/'.join([str(p.bytes_used) for p in metadata.planes]))

        # Image data can be accessed here, but the FrameBuffer
        # must be mapped by the application

    # Re-queue the Request to the camera.
    request.reuse()
    camera.queue_request(request)


# ----------------------------------------------------------------------------
# Camera Naming.
#
# Applications are responsible for deciding how to name cameras, and present
# that information to the users. Every camera has a unique identifier, though
# this string is not designed to be friendly for a human reader.
#
# To support human consumable names, libcamera provides camera properties
# that allow an application to determine a naming scheme based on its needs.
#
# In this example, we focus on the location property, but also detail the
# model string for external cameras, as this is more likely to be visible
# information to the user of an externally connected device.
#
# The unique camera ID is appended for informative purposes.
#
def camera_name(camera):
    props = camera.properties
    location = props.get(libcam.properties.Location, None)

    if location == libcam.properties.LocationEnum.Front:
        name = 'Internal front camera'
    elif location == libcam.properties.LocationEnum.Back:
        name = 'Internal back camera'
    elif location == libcam.properties.LocationEnum.External:
        name = 'External camera'
        if libcam.properties.Model in props:
            name += f' "{props[libcam.properties.Model]}"'
    else:
        name = 'Undefined location'

    name += f' ({camera.id})'

    return name


def main():
    global camera

    # --------------------------------------------------------------------
    # Get the Camera Manager.
    #
    # The Camera Manager is responsible for enumerating all the Camera
    # in the system, by associating Pipeline Handlers with media entities
    # registered in the system.
    #
    # The CameraManager provides a list of available Cameras that
    # applications can operate on.
    #
    # There can only be a single CameraManager within any process space.

    cm = libcam.CameraManager.singleton()

    # Just as a test, generate names of the Cameras registered in the
    # system, and list them.

    for camera in cm.cameras:
        print(f' - {camera_name(camera)}')

    # --------------------------------------------------------------------
    # Camera
    #
    # Camera are entities created by pipeline handlers, inspecting the
    # entities registered in the system and reported to applications
    # by the CameraManager.
    #
    # In general terms, a Camera corresponds to a single image source
    # available in the system, such as an image sensor.
    #
    # Application lock usage of Camera by 'acquiring' them.
    # Once done with it, application shall similarly 'release' the Camera.
    #
    # As an example, use the first available camera in the system after
    # making sure that at least one camera is available.
    #
    # Cameras can be obtained by their ID or their index, to demonstrate
    # this, the following code gets the ID of the first camera; then gets
    # the camera associated with that ID (which is of course the same as
    # cm.cameras[0]).

    if not cm.cameras:
        print('No cameras were identified on the system.')
        return -1

    camera_id = cm.cameras[0].id
    camera = cm.get(camera_id)
    camera.acquire()

    # --------------------------------------------------------------------
    # Stream
    #
    # Each Camera supports a variable number of Stream. A Stream is
    # produced by processing data produced by an image source, usually
    # by an ISP.
    #
    #   +-------------------------------------------------------+
    #   | Camera                                                |
    #   |                +-----------+                          |
    #   | +--------+     |           |------> [  Main output  ] |
    #   | | Image  |     |           |                          |
    #   | |        |---->|    ISP    |------> [   Viewfinder  ] |
    #   | | Source |     |           |                          |
    #   | +--------+     |           |------> [ Still Capture ] |
    #   |                +-----------+                          |
    #   +-------------------------------------------------------+
    #
    # The number and capabilities of the Stream in a Camera are
    # a platform dependent property, and it's the pipeline handler
    # implementation that has the responsibility of correctly
    # report them.

    # --------------------------------------------------------------------
    # Camera Configuration.
    #
    # Camera configuration is tricky! It boils down to assign resources
    # of the system (such as DMA engines, scalers, format converters) to
    # the different image streams an application has requested.
    #
    # Depending on the system characteristics, some combinations of
    # sizes, formats and stream usages might or might not be possible.
    #
    # A Camera produces a CameraConfigration based on a set of intended
    # roles for each Stream the application requires.

    config = camera.generate_configuration([libcam.StreamRole.Viewfinder])

    # The CameraConfiguration contains a StreamConfiguration instance
    # for each StreamRole requested by the application, provided
    # the Camera can support all of them.
    #
    # Each StreamConfiguration has default size and format, assigned
    # by the Camera depending on the Role the application has requested.

    stream_config = config.at(0)
    print(f'Default viewfinder configuration is: {stream_config}')

    # Each StreamConfiguration parameter which is part of a
    # CameraConfiguration can be independently modified by the
    # application.
    #
    # In order to validate the modified parameter, the CameraConfiguration
    # should be validated -before- the CameraConfiguration gets applied
    # to the Camera.
    #
    # The CameraConfiguration validation process adjusts each
    # StreamConfiguration to a valid value.

    # Validating a CameraConfiguration -before- applying it will adjust it
    # to a valid configuration which is as close as possible to the one
    # requested.

    config.validate()
    print(f'Validated viewfinder configuration is: {stream_config}')

    # Once we have a validated configuration, we can apply it to the
    # Camera.

    camera.configure(config)

    # --------------------------------------------------------------------
    # Buffer Allocation
    #
    # Now that a camera has been configured, it knows all about its
    # Streams sizes and formats. The captured images need to be stored in
    # framebuffers which can either be provided by the application to the
    # library, or allocated in the Camera and exposed to the application
    # by libcamera.
    #
    # An application may decide to allocate framebuffers from elsewhere,
    # for example in memory allocated by the display driver that will
    # render the captured frames. The application will provide them to
    # libcamera by constructing FrameBuffer instances to capture images
    # directly into.
    #
    # Alternatively libcamera can help the application by exporting
    # buffers allocated in the Camera using a FrameBufferAllocator
    # instance and referencing a configured Camera to determine the
    # appropriate buffer size and types to create.

    allocator = libcam.FrameBufferAllocator(camera)

    for cfg in config:
        allocated = allocator.allocate(cfg.stream)
        print(f'Allocated {allocated} buffers for stream')

    # --------------------------------------------------------------------
    # Frame Capture
    #
    # libcamera frames capture model is based on the 'Request' concept.
    # For each frame a Request has to be queued to the Camera.
    #
    # A Request refers to (at least one) Stream for which a Buffer that
    # will be filled with image data shall be added to the Request.
    #
    # A Request is associated with a list of Controls, which are tunable
    # parameters (similar to v4l2_controls) that have to be applied to
    # the image.
    #
    # Once a request completes, all its buffers will contain image data
    # that applications can access and for each of them a list of metadata
    # properties that reports the capture parameters applied to the image.

    stream = stream_config.stream
    buffers = allocator.buffers(stream)
    requests = []
    for i in range(len(buffers)):
        request = camera.create_request()

        buffer = buffers[i]
        request.add_buffer(stream, buffer)

        # Controls can be added to a request on a per frame basis.
        request.set_control(libcam.controls.Brightness, 0.5)

        requests.append(request)

    # --------------------------------------------------------------------
    # Start Capture
    #
    # In order to capture frames the Camera has to be started and
    # Request queued to it. Enough Request to fill the Camera pipeline
    # depth have to be queued before the Camera start delivering frames.
    #
    # When a Request has been completed, it will be added to a list in the
    # CameraManager and an event will be raised using eventfd.
    #
    # The list of completed Requests can be retrieved with
    # CameraManager.get_ready_requests(), which will also clear the list in the
    # CameraManager.
    #
    # The eventfd can be retrieved from CameraManager.event_fd, and the fd can
    # be waited upon using e.g. Python's selectors.

    camera.start()
    for request in requests:
        camera.queue_request(request)

    sel = selectors.DefaultSelector()
    sel.register(cm.event_fd, selectors.EVENT_READ, lambda fd: handle_camera_event(cm))

    start_time = time.time()

    while time.time() - start_time < TIMEOUT_SEC:
        events = sel.select()
        for key, mask in events:
            key.data(key.fileobj)

    # --------------------------------------------------------------------
    # Clean Up
    #
    # Stop the Camera, release resources and stop the CameraManager.
    # libcamera has now released all resources it owned.

    camera.stop()
    camera.release()

    return 0


if __name__ == '__main__':
    sys.exit(main())