Demonstration of vx vxsh

Executing operating system commands from within python

Consider that we wish to execute the following command in the operating system; i.e., outside of python:

      vmean if=image1 of=image2 xy=3

This is a VisionX V4 mean filter command that will filter the image file 'image1' with a mean filter of size 3x3 and store the result in the image file 'image2'.

In the sh command language the parameter values are often located in variables to facilitate script programming:

         imin="image1"
         imres='image2'
         window=3
         vmean if=$imin of=$imres xy=$window

This may also be accomplished in Python with a less convenient syntax:

         imin = 'image1';
         imres = 'image2';
         window = 3;
         os.system( 'vmean if=' + imin + ' of=' + imres + ' xy=' + str(window) );

An alternative is to construct the string to be executed with a format statement; however, both of these options are much less convenient than the sh counterpart. The v4 utilities contain a parser called 'vxsh' that simplifies the specification of this command to:

     exec(vx.vxsh( 'vmean if=$imin of=$imres xy=$window' ));

which may be compared to the sh example. The values prefixed with a $ are replaced by their Python variable values using a similar syntax to sh.

Executing operating system commands on python vx images:

In addition to strings and numerical values, the parameters passed to vxsh commands may be Python vx images.

from v4 import vx
#create a vx image in python
x = vx.Vx("int16", [0, 6, 0, 4],1);
x.i[0][2] = 100;
x.i[2][4] = 200;
print('input image x')
print(x.i)
window = 3;
y = vx.Vx(); # a return image must be decared before the call to vx.vxsh

exec(vx.vxsh( 'vmean if=$x of=$y xy=$window' ));

print('result image y')
print(y.i)

input image x
[[  0   0 100   0   0   0]
 [  0   0   0   0   0   0]
 [  0   0   0   0 200   0]
 [  0   0   0   0   0   0]]
result image y
[[ 0 11 11 11  0  0]
 [ 0 11 11 33 22 22]
 [ 0  0  0 22 22 22]
 [ 0  0  0 22 22 22]]

---

Note, the image to be returned to Python is identified by the prefix 'of=' The above exec-vx.vxsh statement

vmean if=$x of=$y xy=$window

is equivalent to the following:

import os
x.write('temp1')
os.system('vmean if=temp1 of=temp2 xy=' + str(window) );
y = vx.Vx('temp2')
os.system('rm -f temp1 temp2' );

Returning a text response from an external system command with vxsh

Text output that is generated by system commands can also be returned to Python using following the command with a call to vxshreturn() as shown below. This method is to be used for all text returns while the 'of=' syntax may only be used for images. Commands that produce csv or other text files may also be read by Python using this method.

exec(vx.vxsh('vps if=$x'))
print(vx.vxshreturn())

 Global Statistics Summary

1 images in file    6 x 4 (0,0)

24         (2         ) number of pixels
200        (200       ) maximum pixel value
0          (100       ) minimum pixel value
200        (100       ) range
12.5       (150       ) mean pixel value
1927.08    (2500      ) variance
43.8986    (50        ) standard deviation
3.55549    (0         ) skewness
14.531     (1.00002   ) kurtosis

Details and Restrictions

Vxsh provides a convenient method for executing external operating system commands by implementing a command line syntax similar to that implemented by the UNIX/Linux sh shell command. Values to be used from the local environment are are specified by preceding their name with a $ as is the convention with sh shell variables. With this syntax, visionx images in the python environment and external visionx images can be conveniently specified in a single command. The details and restriction on vxsh capability are as follows:

1. vxsh converts a shell command string into a form that can be executed by the exec command in in the external system in which python is running Thus, the result of vxsh should always be executed by the system exec() function
2. vxsh conveys simple variables and visionx images to the command by using a $ prefix to each variable name.
3. \$ variables can be one of a character string, a numeric value or a VisionX image (Vx())
4. A single VisionX image result that is specified by an of= parameter in the command may be returned to the local environment. The Vx() structure for this image must be defined before the command is executed.
5. Any text response (stdout) from that the command produces when it executes may be accessed by calling the function vxshreturn()