wilcrofter/gens.jl

A Julia package to generate the nonzero entries of a system matrix.

GenS

A Julia package in support of co-robotic ultrasound tomography

Ultrasound time-of-flight tomography involves construction of a system matrix. Although sparse, a system matrix contains a large number of non-zero elements whose computation can be time consuming when implemented in interpreted scientific programming languages such as Matlab or R. The utilities in this package are implemented in Julia whose speed rivals that of a compiled language, and whose cross-platform compatibility and ease of coding rivals that of Matlab or R.

The package contains Julia utilities to generate the non-zero elements of a system matrix and to read and write such data to disk in cross-language binary form. In addition, the package contains m-files to read and write the data in Matlab or Octave. To date the m-files have only been tested in Octave.

The Julia utilities of primary interest are genS and writeSData.

genS(width, height, gridsize, xmitr, rcvr)

Given a grid determined by width, height, and gridsize, and given transmitter and receiver locations relative to that grid, return a square array whose i,j^th^ entry indicates the pixels crossed on the path from transmitter i to receiver j, and their respective lengths.

The grid is assumed to extend from the origin gridsize*width units in the horizontal (first coordinate) direction and gridsize*height coordinates in the vertical (second coordinate) direction. Transmitter and receiver coordinates should be relative to the same origin. Otherwise, the number and arrangement of transducers is independent of grid specifications.

Transducer positions should be given as nx2 arrays, where n is the number of transducers per probe. The return values of function probePos exemplify the format.

The returned value is an nxn array of type Any, where n is the number of transducers. Each entry i,j, is, itself, an array of type Any containing two members, a 2D Int32 array containing indices of pixels crossed by path i to j and a 1D Float64 array containing corresponding lengths. The S matrix can be easily construced with this information.

The choice of Int32, as opposed to Int or Int64 is for safety. R, for instance, does not yet support 64 bit integers. Moreover, there are still 32-bit machines around.

writeSData(stream, width, height, gridsize, xmitr, rcvr, data)

Write data sufficient to construct a system matrix and to identify the grid and probe positions to which it pertains. Matlab/Octave functions to read this data are provided in m files with appropriate names.

The Matlab/Octave function of primary interest is readSData. It is not yet documented but its function signature is:

function [width, height, gridsize, xmitr, rcvr, data] = readSData (fid)

where data is a cell array whose contents correspond to the Any array of the same name in Julia. An Any array in Julia is essentially the same data structure as a cell array in Matlab. Thus in Matlab, data{i, j} is itself a cell array containing the non-zero pixel crossings on the path from transmitter i to receiver j. Its first element, data{i,j}{1} is a matrix of 2 columns giving the horizontal and vertical indices of a pixel. Its second element data{i,j}{2} is a matrix of 1 column giving the corresponding lengths.

gens.jl's Issues

Zero index

I'm calling genS with incorrect parameters but at the entry for (5,6), that is xmitr 5 and rcvr 6, a zero for the row index appears. The following code calls probePos and genS (with incorrect parameters) and prints the xmitr,rcvr pairs followed by a list of values which are linear combinations of the i,j indices associated with the pairs. For (xmitr,rcvr)==(5,6) the first entry is 0.

using GenS

function zeroRow()
r2 = Float64[-.1 8.1; -.1 -0.1; 8.1 -0.1; 8.1 8.1]
grid = .5
width = 8
height = 8
xmitr,rcvr = probePos(8,r2)
data = genS(width,height,grid,xmitr,rcvr)
for (j in 1:height)
for (i in 1:width)
col = (data[i,j][1][:,1]-1)*width + data[i,j][1][:,2]
println(i," ",j," * ",col)
end #i
end #j
end #function

Copy GenS mfiles to another location

GenS includes four m-files. The package directory is probably not the most convenient place for them. However, they are easily copied to another location. The following shows how I copy them to my desktop using the Julia function, cp. Note that * is Julia's string concatenation operator

julia> cp(Pkg.dir("GenS") * "/mfiles", "/home/wil/Desktop/mfiles")

Use and development of GenS

Basic installation

Installing GenS as a Julia package requires that git be installed on your system. Then, from the Julia prompt, either of the following commands should work. (Let me know if they don't.)

julia> Pkg.clone("[email protected]:WilCrofter/GenS.jl.git")

or

julia> Pkg.clone("https://github.com/WilCrofter/GenS.jl.git")

(Alternatively, if you have a GitHub account, you can fork the repository and install from the fork, replacing WilCrofter in the above commands with your own GitHub user name.)

Assuming the above commands work, GenS will be installed in Julia's package directory. Its location can be found using Pkg.dir:

julia> Pkg.dir("GenS")

To verify, package tests can be run as follows

julia> Pkg.build("GenS");Pkg.reload("GenS");Pkg.test("GenS")

which should result in output resembling:

WARNING: replacing module GenS
INFO: Testing GenS
INFO: Any["wCrossings (vert) OK" true
    "wCrossings (hor) OK" true
    "wCrossings (slant) OK" true
    "gridCrossings OK" true
    "gridCrossings time" 0.00023827
    "segmentLengths OK" true
    "segmentLenths time" 0.000338441221
    "probePos probe 1 OK" true
    "probePos probe 2 OK" true
    "IO: width OK" true
    "IO: height OK" true
    "IO: gridsize OK" true
    "IO: transmitters OK" true
    "IO: receivers OK" true
    "IO: data OK" true
    "genS I/O consistency OK" true
    "genS time (128 transducers)" 5.266795331]
INFO: GenS tests passed

Contributing and updating

The git GUI may be useful if you are unfamiliar with git. It is fairly easy to update the package from the command line or Julia prompt, however. In either case you must first navigate to the package directory (as given by julia> Pkg.dir("GenS").) In Julia:

julia> cd(Pkg.dir("GenS"))
julia> ;git pull # the semicolon causes the command to be issued to the operating system

In a terminal

cd /path/to/GenS
git pull

To contribute code, bug fixes, etc., you must be a collaborator or must issue a pull request from a forked repository. For either purpose you must have a GitHub account.

Contributors will need some familiarity with git, with the commands git add, git commit, and git push at a minimum.