Skip to content

Latest commit

 

History

History
149 lines (115 loc) · 6.08 KB

api-examples.rst

File metadata and controls

149 lines (115 loc) · 6.08 KB
Raw

API and Two Simple Example Programs

The API for imageZMQ consists of 2 classes with 2 methods each. The ImageSender class has 2 methods: one for sending an OpenCV image and one for sending a jpg compressed OpenCV image. The ImageHub class has 2 methods: one for receiving an OpenCV image and one for receiving a jpg compressed OpenCV image.

Each ImageSender/ImageHub pair can work in one of following modes: REQ/REP or PUB/SUB. The mode is selected when ImageSender and ImageHub are instantiated by setting REQ_REP parameter in constructor to True or False. REQ/REP mode is the default. There are advantages and disadvantages for each pattern. For further details, see: REQ/REP versus PUB/SUB Messaging Patterns.

imageZMQ API

 1 class ImageSender(connect_to='tcp://127.0.0.1:5555', REQ_REP = True):
 2     Opens a zmq socket (REQ type if REQ_REP == True, PUB type if REQ_REP == False)
 3     on the image sending computer, typically a Raspberry Pi, that will be sending
 4     OpenCV images and related text messages to the hub computer. Provides methods
 5     to send images or send jpg compressed images.
 6 
 7     Arguments:
 8       connect_to: the tcp address and port of the hub computer
 9            Example format: connect_to='tcp://192.168.1.17:5555'
10            Example format: connect_to='tcp://jeff-macbook:5555'
11       REQ_REP: whether to use REQ/REP messaging pattern or not.
12            Example: REQ_REP = True (default) The sender will be
13                     use a REQ/REP pattern.
14                     REQ_REP = False The sender will use a PUB/SUB
15                     pattern
16 
17     send_image(self, msg, image):
18         Sends OpenCV image and msg to hub computer.
19 
20         Arguments:
21           msg: text message or image name.
22           image: OpenCV image to send to hub.
23         Returns:
24           A text reply from hub.
25 
26     send_jpg(self, msg, jpg_buffer):
27         Sends msg text and jpg buffer to hub computer.
28 
29         Arguments:
30           msg: image name or message text.
31           jpg_buffer: bytestring containing the jpg image to send to hub.
32         Returns:
33           A text reply from hub.
34 
35     close(self):
36         Closes the ZMQ socket and the ZMQ context.
37 
38 
39 class ImageHub(open_port='tcp://:5555', REQ_REP = True):
40     Opens a zmq socket on the hub computer (REP type if REQ_REP = True,
41     SUB type otherwise), for example, a Mac, that will be receiving and
42     displaying or processing OpenCV images and related text messages.
43     Provides methods to receive images or receive jpg compressed images.
44 
45     Arguments:
46       open_port: (optional) the socket to open for receiving REQ requests.
47       REQ_REP: (optional) whether to use REQ/REP messaging pattern or not.
48       Example: REQ_REP = True (default) The Hub will be
49                use a REQ/REP pattern.
50                REQ_REP = False The Hub will use a PUB/SUB
51                pattern
52 
53 
54     recv_image(self, copy=False):
55         Receives OpenCV image and text msg.
56 
57         Arguments:
58           copy: (optional) zmq copy flag.
59         Returns:
60           msg: text msg, often the image name.
61           image: OpenCV image.
62 
63     recv_jpg(self, copy=False):
64         Receives text msg, jpg buffer.
65 
66         Arguments:
67           copy: (optional) zmq copy flag
68         Returns:
69           msg: text message, often image name
70           jpg_buffer: bytestring jpg compressed image
71 
72     connect(self, open_port):
73         In PUB/SUB mode, the hub can connect to multiple senders at the same
74         time. Use this method to connect (and subscribe) to additional senders.
75 
76         Arguments:
77           open_port: the PUB socket to connect to
78 
79     send_reply(self, reply_message=b'OK'):
80         Sends the zmq REP reply message.
81 
82         Arguments:
83           reply_message: reply message text, often just the string 'OK'
84 
85     close(self):
86         Closes the ZMQ socket and the ZMQ context.

Two Simple Example Programs using the REQ/REP messaging pattern

The simple test and example programs mentioned below show how to use the API. All 4 of these programs are found in the tests folder.

The programs timing_send_images.py and timing_receive_images.py provide examples of how to use the imageZMQ API to send and receive OpenCV images. The programs show a simple imageZMQ use case. Additional image processing in the sending program would typically be placed between the picam.read() and the sender.send_image() lines. Such processing would be done with calls to methods for image rotation, resizing, dilation, etc. The program that is receiving images would do other processing and save the images to disk using the text portion of the image message to categorize or label the image file. See the comments in these programs for more details on where these statements would be placed.

The programs timing_send_jpg_buf and timing_receive_jpg_buf show how imageZMQ would be used to send jpg compressed OpenCV images to reduce network load. The programs show how the conversion from OpenCV image format to a jpg bytestring would be done by the application program. These programs show how to perform the conversion using OpenCV's cv2.imencode() and cv2.imdecode() methods.

Using both messaging patterns together in a web streaming application

It is possible to use both the REQ/REP and PUB/SUB patters in the same application. That way, part of the application can be tightly coupled (and therefore blocking) using REQ/REP while another part can be a non-blocking web stream using PUB/SUB. Three programs demonstrate this are included in the examples folder. There is a detailed explanation of these web streaming example programs here.

Return to main documentation page README.rst