Ipcam Buffers.book

Transcript

1 T F A R D Basler Components Using IP Camera Live Buffers and Alarm Buffers APPLICATION NOTES Document Number: AW000810 Version: 03 Language: 000 (English) Release Date: 6 August 2010 Contacting Basler Support Worldwide Europe and the Middle East: Basler AG An der Strusbek 60 - 62 22926 Ahrensburg Germany Phone: +49-4102-463-303 Fax: +49-4102-463-599 Email: [email protected] The Americas: Basler, Inc. 855 Springdale Drive, Suite 203 Exton, PA 19341 U.S.A. Phone: +1-610-280-0171 Fax: +1-610-280-7608 Email: [email protected] Asia: Basler Asia Pte. Ltd 8 Boon Lay Way # 03 - 03 Tradehub 21 Singapore 609964 Phone: +65-6425-0472 Fax: +65-6425-0473 Email: [email protected] www.basler-ipcam.com All material in this publication is subject to change without notice and is copyright Basler Vision Technologies. Using IPCam Live Buffers and Alarm Buffers 1 Introduction The Basler IP Camera can provide up to three video streams simultaneously. In brief, this means, that you can specify up to three different rectangular regions of the camera's sensor, and you can assign each region to an individually configured video stream ("individually" not only means that each stream shows a different field of view, it also means that each stream can use a different encoder, image quality, bit rate, frame rate, etc.). When the camera is first powered on, at least one video stream, stream 0, becomes immediately active and cannot be switched off. The other two streams, stream 1 and stream 2, can be enabled or disabled as you desire. Even if the camera is not connected to a network, it immediately begins capturing images and storing them in the camera's internal buffers. It is important to know, that each of the three available video steams has two dedicated image buffers, a Live Buffer and an Alarm Buffer. As soon as a video stream is enabled (for example, stream 0 which will be automatically enabled when the camera is powered on), the camera begins placing the captured images in the stream into the live buffer for the stream. If the alarm buffer for the stream is properly configured and is "armed", the same images will also be placed into the alarm buffer for the stream. The size of each buffer is configurable and can range from 2048 to 57856 KB. The buffers are implemented as ring buffers. This means that once a buffer is full, as newer images are placed into the buffer they will begin overwriting the oldest images. As shown in Figure 1 on page 2, when the camera captures image 15 and transfers it via stream 0 to the buffers, image 15 is written into the current position of the live buffer and the alarm buffer. Once this is done, the buffers rotate by one image position. The old image at this position (image 4) will now be overwritten by the next image captured. In Figure 1, the live buffer and the alarm buffer are only shown for stream 0. But of course, stream 1 and stream 2 each have their own live buffer and alarm buffer as well. As mentioned earlier, the writing of image data into the buffers happens totally independently from the transmission of the image data over the Ethernet. Even if a camera wasn’t connected to a network at all, it would still capture images and store them in the ring buffers for each enabled stream as long as the camera is powered on. The number of images that can fit into a ring buffer depends on the size of the buffer and the size of the compressed images. On the IP Camera, the size of the buffers on each stream is configurable, as is the size of the images in the stream. The alarm buffer on each stream can also be disabled if desired. Application Notes 1 Using IPCam Live Buffers and Alarm Buffers Existing image in the live buffer will be overwritten DSP Stream 0 Stream 0 4 15 15 14 5 13 Live Buffer 6 Image captured by the sensor 12 7 11 8 4 10 9 15 Existing image in the alarm buffer will be overwritten 14 13 5 Alarm Buffer 6 12 7 IP Camera POE Connector Sensor 11 8 9 10 Fig. 1: Buffers on Stream 0 2 Application Notes Using IPCam Live Buffers and Alarm Buffers 2 A Closer Look at Live Buffers If a client requests access to a video stream, by default the client would access the content of the live buffer at the position where the most recent images are entering the buffer (image 15 in Figure 2). Assuming that you want to access stream 0 and that stream 0 is set for MJPEG encoding, using a request similar to this: http:///cgi-bin/mjpeg?buffer=0&mode=live would yield a stream that includes the most current images as shown in Figure 2. However, the client can also access the image data stored at any position of the ring buffer. This means that the client can "look back into history" and get images that were captured some time ago. This is done by issuing a request that includes the "timeshift" and "seek" parameters A request similar to this: http:///cgi-bin/mjpeg?buffer=0&mode=timeshift&seek=2000 would yield a stream that includes images captured 2000 ms ago as shown in Figure 3 on page 4. Most current captured images are streamed Sensor DSP Stream 0 Stream 0 4 15 15 14 5 13 Live Buffer 6 12 7 Image captured by sensor 11 8 4 9 15 10 14 13 5 Alarm Buffer 6 12 7 IP Camera Live Stream 0 11 8 9 10 Fig. 2: A Live Stream with the Most Current Images Application Notes 3 Using IPCam Live Buffers and Alarm Buffers Sensor DSP Live Stream 0 Stream 0 Stream 0 4 15 15 14 5 13 Live Buffer 6 Image captured by the sensor 12 7 11 8 4 9 10 15 14 5 13 Alarm Buffer 6 12 7 IP Camera Images captured 2000 ms ago are streamed 11 8 9 10 Fig. 3: A Live Stream with Images Captured in the Past 4 Application Notes Using IPCam Live Buffers and Alarm Buffers In the Basler Surveillance Web Client interface, the camera provides the functions needed to administer the live buffer for each stream on the Stream 0, Stream 1, and Stream 2 tabs of the Streaming parameters group. The tab for Stream 0 is illustrated in Figure 4. The Stream 0, Stream 1, and Stream 2 tabs let you do the following: „ Check the current size of the live buffer for Stream 0, Stream 1, or Stream 2. „ Set the size of the live buffer for Stream 0, Stream 1, or Stream 2. Fig. 4: Streaming Parameters Group The live buffer functionality displayed on the Stream 0, Stream 1, and Stream 2 tabs shown in Figure 4 can also be accessed via the camera API. You can using requests similar to the following to check the live buffer size on stream 0: http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.StreamSelector.SetValue&Parameter_0_0=0 http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.LiveBufferSize.GetValue Or you can use requests similar to the following to set the live buffer size on stream 0 to 9600 kBytes (note that the camera must be set to configuration mode before you can set the live buffer size): http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Global.OperationMode.SetValue&Parameter_0_0=Configure Application Notes 5 Using IPCam Live Buffers and Alarm Buffers http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.StreamSelector.SetValue&Parameter_0_0=0 http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.LiveBufferSize.SetValue&Parameter_0_0=9600 where: = the IP address or the host name of the camera For more information about using the Basler surveillance web client to set the live buffer related parameters, see the IP Fixed Camera User’s Manual or the IP Fixed Dome Camera User’s Manual. For detailed information about using the camera API to set the live buffer related parameters, see the IP Fixed Camera and IP Fixed Dome Camera API Description. Both of these documents are available for download at: www.baslerweb.com 6 Application Notes Using IPCam Live Buffers and Alarm Buffers 3 A Closer Look at Alarm Buffers When the alarm buffer on a stream is enabled and "armed", the images captured by the sensor are placed into the alarm buffer in the same manner as they are in a live buffer. Typically, the alarm buffer on a stream is configured for a larger size than the live buffer, so that the alarm buffer can hold more images. The point at which an alarm buffer begins to work differently than a live buffer is when an alarm condition is declared. When an alarm condition is declared (for example, by the camera’s built-in motion detection function or by an external signal applied to the camera's digital input), the camera will continue putting images into the alarm buffer up to a certain point and then will STOP. This "certain point" can be configured by setting the "Post Alarm Buffer Size" parameter. When you configure an alarm buffer, you must configure both the total size of the buffer and the size of the "post alarm" part of the buffer. The post alarm part of the alarm buffer is reserved for images that are captured immediately AFTER an alarm occurs. As an example, assume that the Alarm Buffer Size parameter is set to a value that will allow the alarm buffer to hold a total of 12 images (in reality, the storage capacity is much larger). Also assume that the Post Alarm Buffer Size parameter is set to a value that will allow the post-alarm portion of the alarm buffer to hold 9 images. And finally, assume that the buffer has been set to an "armed" state. When the alarm buffer is in an "armed" state, images are stored in the buffer similar to the way they are in a live buffer. When the buffer becomes full, newly captured images overwrite the older images. The "armed" designation simply means that the buffer is ready to react properly when an alarm condition is declared. When an alarm condition is declared, the camera will begin to put captured images into the postalarm portion of the buffer as shown in Figure 5. The camera will continue putting captured images into the alarm buffer until the post-alarm portion is full. At that point, the camera will STOP putting images into the alarm buffer. In the case of our example camera, this means that 9 images will be captured and stored after the alarm condition is declared. The total result is that the buffer now contains 3 images that were captured before the alarm condition was declared and 9 images that were captured after the alarm was declared as shown in Figure 6. While the buffer is accumulating post alarm images, it is said to be in an "active" state. And when it has stopped and is filled with pre and post alarm images, it is said to be in a "done" state. The buffer will remain in the "done" state and the images will remain in the alarm buffer until the alarm buffer has been rearmed. And if there are no devices requesting a stream from the camera, all of this can happen without causing any network load! Application Notes 7 Using IPCam Live Buffers and Alarm Buffers Sensor DSP Live Stream 0 Stream 0 Stream 0 13 24 24 23 22 14 Live Buffer 15 Image captured by sensor 20 16 17 Alarm condition declared Images begin filling post alarm portion of the buffer Buffer is in an "active" state 13 18 24 19 23 22 14 Alarm Buffer 15 Orange = post alarm portion of the buffer IP Camera 21 21 16 20 17 18 19 Fig. 5: Alarm Condition Declared - Alarm Buffer Active Sensor DSP Live Stream 0 Stream 0 Stream 0 33 44 44 43 42 34 Live Buffer 35 Image captured by sensor 41 36 40 37 Alarm buffer in a "done" state - No more images are placed in the buffer 21 38 32 39 31 30 22 Pre alarm images Alarm Buffer 23 29 24 28 25 IP Camera Post alarm images 26 27 Fig. 6: Alarm Buffer Done 8 Application Notes Using IPCam Live Buffers and Alarm Buffers When the alarm buffer is in the done state, a client (such as a media player) can request access to a video stream from the buffer. Assuming that you want to access the alarm buffer for stream 0 and that stream 0 is set for MJPEG encoding, a request similar to this: http:///cgi-bin/mjpeg?buffer=1&mode=replay&fps=5.0 where: = the IP address or the host name of the camera would yield a stream that includes the images held in the alarm buffer (as shown in Figure 7). The stream would send the images in the alarm buffer at a rate of five frames per second and would stop when all of the images in the buffer have been streamed. Sensor DSP Live Stream 0 Stream 0 Stream 0 59 70 70 69 60 68 Live Buffer 61 Image captured by the sensor 67 62 66 63 21 Images stored in the buffer are streamed 64 32 65 31 30 22 Alarm Buffer 23 29 28 24 IP Camera Alarm Stream 0 25 26 27 Fig. 7: A Stream from an Alarm Buffer in the Done State If stream 0 is set for MPEG4 encoding, you can access the alarm buffer for stream 0, using a request similar to this: rtsp://mpeg4?buffer=1&mode=replay&fps=5.0 If stream 0 is set for H.264 encoding, you can access the alarm buffer for stream 0, using a request similar to this: rtsp://h264?buffer=1&mode=replay&fps=5.0 Note that if the fps parameter is omitted, the camera will replay the buffer at as fast a speed as possible. This would be the quickest way to download the contents of the buffer. Application Notes 9 Using IPCam Live Buffers and Alarm Buffers You could also use these same requests to initiate a stream from the alarm buffer when the buffer is in an "active" state. This simply means that the camera would begin streaming the oldest images out of the buffer while post alarm images are being added to the buffer. The camera will continue to place post alarm images into the buffer as it normally would until the buffer is full. And the camera would continue to stream images out of the buffer until it has streamed the complete contents of the buffer. You cannot stream images out of an alarm buffer when it is disabled, and we do not recommend attempting to stream images out of a buffer that is in an "armed" state. In the Basler Surveillance Web Client interface, the camera provides the basic functions needed to administer the alarm buffer for each stream on the Stream 0, Stream 1, and Stream 2 tabs of the Streaming parameters group. The tab for Stream 0 is illustrated in Figure 8. The tabs let you do the following: „ Check the current size of the alarm buffer for Stream 0, Stream 1, or Stream 2. „ Set the size of the alarm buffer for Stream 0, Stream 1, or Stream 2. „ Set the size of the portion of the alarm buffer for Stream 0, Stream 1, or Stream 2 that will be used to store post alarm images. Fig. 8: Streaming Parameters Group 10 Application Notes Using IPCam Live Buffers and Alarm Buffers The alarm buffer functionality displayed on the Stream 0, Stream 1, and Stream 2 tabs shown in Figure 8 can also be accessed via the camera API. You can use requests similar to the following to check the alarm buffer size on stream 0: http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.StreamSelector.SetValue&Parameter_0_0=0 http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.AlarmBufferSize.GetValue You can use requests similar to the following to set the alarm buffer size on stream 0 to 32768 kBytes and the post alarm buffer size to 16384 kBytes (note that the camera must be set to configuration mode before you can set an alarm buffer size): http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Global.OperationMode.SetValue&Parameter_0_0=Configure http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.StreamSelector.SetValue&Parameter_0_0=0 http:///cgi-bin/param_if.cgi?NumActions=2 &Action_0=Stream.AlarmBufferSize.SetValue&Parameter_0_0=32768 &Action_1=Stream.PostAlarmBufferSize.SetValue&Parameter_1_0=16384 where: = the IP address or the host name of the camera Application Notes 11 Using IPCam Live Buffers and Alarm Buffers Additional functions needed to administer the alarm buffer for each stream are available in the Alarm Buffers section of the Alarm Handling parameters group as illustrated in Figure 9. These tabs let you do the following: „ Check the current state of the alarm buffer for Stream 0, Stream 1, or Stream 2. „ Disable the alarm buffer for Stream 0, Stream 1, or Stream 2. „ Arm the alarm buffer for Stream 0, Stream 1, or Stream 2 (if an alarm buffer is disabled, arming the alarm buffer will also enable it). Fig. 9: Alarm Handling Parameters Group The alarm buffer functionality displayed on the Stream 0, Stream 1, and Stream 2 tabs shown in Figure 9 can also be accessed via the camera API using requests similar to the following: http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.StreamSelector.SetValue&Parameter_0_0=0 http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.AlarmBufferState.GetValue http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.AlarmBufferDisable.Execute http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=Stream.AlarmBufferArm.Execute 12 Application Notes Using IPCam Live Buffers and Alarm Buffers For more information about using the Basler surveillance web client to set the alarm buffer related parameters, see the IP Fixed Camera User’s Manual or the IP Fixed Dome Camera User’s Manual. For detailed information about using the camera API to set the alarm buffer related parameters, see the IP Fixed Camera and IP Fixed Dome Camera API Description. Both of these documents are available for download at: www.baslerweb.com Alarm Buffer Use Case: A Supervisory Camera That Normally Uses No Network Bandwidth and No Disk Space You could configure a camera so that it will declare an alarm condition if motion is detected. You could also configure the camera so that an alarm buffer is enabled, the buffer has both pre and post alarm space allocated in it, and the buffer is armed. Assuming that no devices are accessing streams from the camera, the camera will not need to transmit data to any client. This means that the camera will not use any network bandwidth and that no data needs to be stored on a hard disk. Nevertheless, the camera is doing its job - it is supervising the field of view and waiting to detect motion. If an alarm is declared, the camera will begin storing post alarm images in the alarm buffer. The camera can also actively inform a piece of client software (NVR/VMS) that an alarm condition has been declared by pushing an http comment to the client. The client could then, for example, simply request the camera to stream the contents of the alarm buffer because this is the only information that the client is actually interested in. This means that only relevant alarm data is actually using network bandwidth and requiring disk storage. Application Notes 13 Using IPCam Live Buffers and Alarm Buffers 4 Alarm Buffers and SD Card Functionality Basler IP Fixed Dome Cameras have a built-in micro SDHC card slot that can be used for local file storage. The card slot supports SD cards with a capacity of up to 32 GB. When the camera is switched on, it checks to see if a micro SDHC card is present in the card slot. If it detects an SD card, the camera provides the functions needed to administer the SD card in the Basler Surveillance Web Client interface. The functions are available in the interface on the SDCard tab of the System parameters group as illustrated in Figure 10. This tab lets you do the following: „ Check to see if an SD card is present in the SD card slot. „ Check the size of the SD card. „ Check the size of the free space on the SD card. „ Erase the contents of the SD card. Fig. 10: System Parameters Group The functionality displayed on the SDCard tab shown in Figure 10 can also be accessed via the camera API using requests similar to the following: http:///cgi-bin/param_if.cgi?NumActions=3 &Action_0=SDCard.Present.GetValue &Action_1=SDCard.Size.GetValue &Action_2=SDCard.Avail.GetValue http:///cgi-bin/param_if.cgi?NumActions=1 &Action_0=SDCard.Erase.Execute where: = the IP address or the host name of the camera 14 Application Notes Using IPCam Live Buffers and Alarm Buffers The SD card can be configured to act as an "alarm action", i.e., as a medium that will react when a camera alarm condition is declared. The settings used to configure the SD card as an alarm action can be found in the Alarm Sources parameters group of the web client interface. The settings are located in the Alarm Actions section of the group on an SDCard tab as shown in Figure 11. This tab lets you set the following: „ Action Enable - enables the saving of a text file to the SD card when an alarm condition is declared. „ Include Image - enables the inclusion of a captured image along with the text file. (The image is captured at the moment the alarm condition is declared.) „ Text Overlay - sets up a text overlay to apply to the included image. „ Include Stream - enables the saving of video files to the SD card along with the text file. A video file including pre-alarm and post-alarm images will be saved for each alarm buffer that was enabled and armed when the alarm was declared. „ Rearm Alarm Buffer - automatically rearms the alarm buffers after the camera has finished saving the buffer contents to the SD card. „ SDCard Overwrite - allows the camera to overwrite old data if the card is full. Fig. 11: Alarm Actions Parameters Group The functionality displayed on the SDCard tab shown in Figure 11 can also be accessed via the camera API using a request similar to the following: http:///cgi-bin/param_if.cgi?NumActions=5 &Action_0=Alarm.ActionEnable.SetValue&Parameter_0_0=1 &Action_1=Alarm.ActionIncludeImg.SetValue&Parameter_1_0=1 &Action_2=Alarm.ActionIncludeStream.SetValue&Parameter_2_0=1 &Action_3=Alarm.SDCardRearmAlarmBuffer.SetValue&Parameter_3_0=1 &Action_4=Alarm.SDCardOverwrite.SetValue&Parameter_4_0=1 Application Notes 15 Using IPCam Live Buffers and Alarm Buffers For more information about using the Basler surveillance web client to set the SD card related parameters, see the IP Fixed Dome Camera User’s Manual. For detailed information about using the camera API to set the SD card related parameters, see the IP Fixed Camera and IP Fixed Dome Camera API Description. Both of these documents are available for download at: www.baslerweb.com If the SD card "Action Enabled" parameter is set to enabled, whenever an alarm condition is declared by the camera, the camera will create a text file containing some basic information about the alarm condition and will save the file to the SD card. If the SD card "Include Image" parameter is enabled, the camera will capture an image at the moment the alarm was declared and this image will be saved to the SD card. You can also configure the camera so that some specific text will be overlayed on the image. The size of the image captured by the sensor and stored on the SD card is determined by the camera’s global AOI parameters. The image does not inherent any of the image settings configured for the image streams (e.g., resolution, quality, etc.). Assuming that the camera is properly configured and that the alarm buffers have been set to an "armed" condition, when an alarm condition is declared, the alarm buffer on each stream will record post-alarm images until the buffer is full. If the SD card "Include Stream" parameter is enabled, the contents of the alarm buffers (both pre and post alarm) will be saved to the SD card when the buffers become full. If the SD card "Rearm Alarm Buffer" parameter is enabled, the alarm buffers will automatically be rearmed once the camera has finished saving the contents of the alarm buffers to the SD card. The settings for each stream, such as the encoder type, quality, resolution, etc., will also be valid for the corresponding video file saved on the SD card. For example: „ If a stream is set for MJPEG encoding, any alarm buffer data saved to the SD card for the stream will be in MJPEG format and the saved file will have an .mjpeg file extension. „ If a stream is set for MPEG4 encoding, any alarm buffer data saved to the SD card for the stream will be in MPEG4 format and the saved file will have an .m4v extension. „ If a stream is set for H.264 encoding, any alarm buffer data saved to the SD card for the stream will be in H.264 format and the saved file will have an .h264 extension. If the "SDCard Overwrite" parameter is enabled, the system will be configured so that old data on the SD card is overwritten when the SD card becomes full. If the parameter is not enabled, recording to the SD card will stop when the card becomes full. If a camera is properly configured, it can act as a self-sufficient system that records video of all alarm events to the SD card without the need for additional software. When an efficient encoder such as H.264 is used and an SD card with sufficient capacity is present, the camera can save video data for several months. Considering the fact that more and more burglars are also stealing the video recorder from a surveillance system, this feature is an important backup solution. 16 Application Notes Using IPCam Live Buffers and Alarm Buffers The camera is equipped with an FTP server and the alarm data stored on the SD card can be accessed via FTP using a web browser. If user management is not enabled on the camera, you could type the following into a web browser’s address field to access the alarm data: ftp:///data/alarms/ If user management is enabled, you would type in the following: ftp://username:password@/data/alarms/ For example, if your camera has an IP address of 172.16.51.105 and user management is not enabled, you would type: ftp://172.16.51.105/data/alarms/ into the address field and then press the Enter key. The browser would return something similar to this: Name Size Date Modified 2010-04-14_10-11-34.jpeg 70.5 kB 4/14/10 10:11:00 AM 2010-04-14_10-11-34.txt 363 B 4/14/10 10:11:00 AM 2010-04-14_10-11-34_0.mjpeg 7.9 MB 4/14/10 10:12:00 AM [parent directory] This example shows what you might see if there was data stored for the occurrence of just one alarm condition on a camera that had a single MJPEG stream enabled. The first file contains the image that was captured when the alarm condition was declared, the second file is the text file that was created when the alarm condition was declared, and the third file is a video file that contains the pre and post alarm images that were stored in the buffer when the buffer reached a "done" state. If data for more alarms has been stored, you will see more available files. And if the stream was set for MPEG4 or H.264 encoding rather than MJPEG, you would see video files with an .m4v or an .h264 file extension rather than an .mjpeg extension. If there is no stored data on the SD card, you will get a "cannot display page" or a "no such file" type of error when you attempt to access the data. You can also access the SD card's file system using the built-in FTP server in the camera and a media player such as the VLC Media Player. The video files can be displayed via the FTP server using a request in the media player such as this: ftp:///data/alarms/ The SD card can also be removed from the camera and inserted into a card reader on a standard PC. Application Notes 17 Using IPCam Live Buffers and Alarm Buffers Video files ending with the .mjpeg, .m4v, and .h264 are not as common as video files such as .mpg or .avi., and some popular video players cannot handle these formats. The free VLC media player can handle all of these formats without difficulty. IP Cam IP Camera 18 Application Notes Revision History Revision History Doc. ID Number Date Changes AW00081001000 23 Mar 2009 Initial release of this document. AW00081002000 2 Aug 2010 Added information to Section 2 and Section 3 describing how to parameterize the buffer functionality using the Basler Surveillance Web Client and using the camera API. Added Section 4 describing the SD Card functionality on dome cameras. AW00081003000 Application Notes 6 Aug 2010 Corrected an error in the stated file name extensions. 19 Revision History 20 Application Notes