vx.vxsh

vx.vxsh(CommandString )


vxsh is a simple command compiler that converts a text string with $-prefixed names to conveniently execute a host system (shell) commands (MAC/Linux). The result must be executed in the current environment with exec. Thus the usual usage is: 

               exec(vx.vxsh(  "<command-string>" ))
External command parameters including numeric values, strings and vx images may be passed to the specified command by the use of $-parameters. Names of external system files may also be passed to the system by $-parameters.


In short, vxsh allows commands for the external system to be conveniently specified, especially for someone experienced in the Linux $-parameters used in command shells. It avoids the explicit transfer of data between the python environment and the external system. This function is still in a early stage of development and parameter substitution has some limitations.

Images that are created by the command are returned to a python vx structure if the parameter of=$≤iname> is specified; where is a predefined vx structure. String responses from the execution of the command may be accessed for the last executed command with the vx.vxshreturn() function.

Parameters
CommandString str: this is the command to be executed. The specified system command(s) are executed with parameter substitution for the $-prefixed names.

vx.vxshreturn()
vxshretun returns any (terminal) text (stdout or stderr) that was generated by the execution of the last command by vx.vxsh().

Examples
1. Direct shell commands
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 (Linux/Mac) 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: 

       imin = 'image1'
       imres = 'image2'
       window = 3
       os.system( 'vmean if=%s of=%s xy=%d' % (imin, imres, window))
This can be specified using vx.vxsh by: 

       imin = 'image1'
       imres = 'image2'
       window = 3
       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.


2. 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. Consider executing the mean operation an the following python vx image. 


from v4 import vx
#create a vx image in python
a = vx.Vx("uint8", [0, 6, 0, 4],1);
a.i[0][2] = 100;
a.i[2][4] = 200;
print('input image a')
print(a.i)

input image a
[[  0   0 100   0   0   0]
 [  0   0   0   0   0   0]
 [  0   0   0   0 200   0]
 [  0   0   0   0   0   0]]
If the given $-parameter is a defined vx structre then vxsh will use the python vx image directly. 

window = 3;
b = vx.Vx(); # a return image must be declared before the call to vx.vxsh
exec(vx.vxsh( 'vmean if=$a of=$b xy=$window' ));
print('result image b')
print(b.i)

result image b
[[ 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='.


3. Returning a text response from an external command

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 from that can be executed by the exec command in in the external system in which python is runnina. 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()