View source for GXS700 FOSS

TLDR 2020:

* This page is very out of date and needs editing
* In 2019 the toolkit was overhauled to be generally a lot nicer but these instructions are out of date
* sudo udev.sh
** Makes sensor easier to use (no "sudo")
* Plug in your sensor to USB port
* python3 main.py --no-xray
* Observe file written to out/ dir


Quick start guide to getting the sensor working.  Basically, follow sections below to:

*Install software
*Force a capture to verify the sensor works
*Fire x-rays at sensor to test full functionality

[[https://github.com/JohnDMcMaster/uvscada/tree/master/gxs700|driver here]]

[[https://siliconpr0n.org/nuc/doku.php?id=gendex:gxs700|Sensor info]]

=WARNING=

x-rays are dangerous…make sure you know what you are doing.  Not responsible for death, injury etc

=Supported devices=

{| class="wikitable sortable" border="1"
!Image!!Vendor!!Product!!Works?!!Notes
|-
| ||Gendex||GXS700 small (type 1)||Yes||Linux VM problematic from Windows VMWare and VirtualBox
|-
| ||Gendex||GXS700 large (type 2)||Yes||Primary device I develop for
|-
| ||Dexis||Platinum||Probably||Test failed but DUT was likely broken
|-
| ||Dexis||Plus 690||Probably||Test failed but DUT was likely broken
|-
|}

I don't know if any other vendors (ex: schick) use the same hardware


=Installation=

Prereq:

*Linux
**Tested on Ubuntu 12.04 x64, Ubuntu 16.04 x64
*USB port (duh)
*A supported sensor
*x-ray source: not needed for initial setup
*You DO NOT need calibration files
**See below for details

"$ cmd" means type "cmd" into a terminal

Do (I'll improve this as people run into problems):

#$ sudo apt-get install -y git python-pip
##Also maybe: sudo apt-get install -y python-serial python-numpy python-PIL
#$ sudo pip install libusb1
#$ git clone [[https://github.com/JohnDMcMaster/uvscada.git|https://github.com/JohnDMcMaster/uvscada.git]]
#$ cd uvscada
#$ ln -s $PWD/uvscada gxs700/
#$ ./gxs700/udev.sh
#Plug in your sensor to the USB port
##Re-plug it if its already plugged in
#$ python gxs700/dump_dev.py
##Optional (highly recommended): backup sensor data
#$ python gxs700/capture.py -f -e
##Optional: test sensor by forcing a capture


=Force capture=

This step tests the sensor without actually firing x-rays at it.  This is also useful for calibrating sensor defects

[[File:mcmaster_gxs700_foss_good.png|300 px]]

#$ python gxs700/capture.py -f -e
#Check which you got:
##Waiting for image: expected response.  Continue below
##"Exception: Failed to find a device": plugged in?  Did you run permission script?
#It should have written capture_000_e.png to the current directory
#You should see an image roughly resembling the noise of the reference above.  If you do, your sensor probably works

=X-ray capture=

[[File:mcmaster_gxs700_foss_sample.jpg|300 px]]

Suggest you force a capture first to verify your sensor is working

#$ python gxs700/capture.py
#Verify it says "Waiting for image".  It will spit out some dots to indicate its still polling
#Fire your x-ray source
#It should notice the x-rays and begin downloading an image
#It should have written capture_000.png to the current directory
##Currently also writes capture_000.bin but will probably remove this soon
#You have your first x-ray!

=Diagnostic dump=

Please do this and send me the result.  This helps me understand the sensors better to provide better support

#$ python gxs700/dump_dev.py

Send me the directory "dump" that it creates.  If you are going to send me data from multiple sensors, please move the directory before re-running as it will overwrite.

[[https://siliconpr0n.org/nuc/doku.php?id=gendex:gxs700_dump|Reference dumps]]


=Troubleshooting=

Troubleshooting:

#Couldn't find device
##Did you run the udev permission script?
##Try re-plugging it in and/or restarting Linux system
##VM: did you connect USB to the guest?
#Didn't detect x-rays
##Can you turn up current higher?
###Only recently added mA monitoring…don't know approx current I was imaging at
##Too high or low kVp?
###60 kVp is a good place to start

Known issues:

#Multiple sensors are not supported
##Would slightly increase software complexity and no use case today for that
#Usually can be interrupted but sometimes will fail init if it is
##Workaround: re-plug the USB port

Misc:

#USB speed limits frame rate to something like 0.3 FPS…don't expect this to work like a video camera
#Currently doesn't use fxload but maybe should
#.bin file is raw output.  .png is lossless compressed .bin equivalent (you can make the .bin from the .png) so .bin will probably get dropped
#Image decoding can probably be made much faster but usually I don't care
##For long runs (ex: CBCT) I'm waiting for sensor to cool anyway

See also: GXS700 general troubleshooting

=Decoding=

decode.py has a "-e" option to do histogram equalization.  This often brings out additional detail by re-mapping from 16 bit grayscale to shifted 8 bit grayscale.  This works because humans can see 8 bits much easier than 16.  TOOD: could we display usable 16 bit images by using two colors?

Example

<code>
$ python decode.py -e capture_004.bin capture_004e.png
</code>

NOTE: future revisions may require .png input instead of .bin

=x-ray trigger=

I haven't messed with the default trigger settings but I suspect you could do very low x-ray triggering if desirable

=x-ray fire=

I use a Gendex GE-100 x-ray head.  I've found these readily available for <$75 on both eBay and Craigslist.  This accepts near line level AC inputs for both HV and filament making this easy to control from commodity variacs.

I control the setup via a DLI WPS7.  When wired correctly:

#Outlet 1: HV
#Outlet 2: filament

do something like:

<code>
$ WPS7_HOST=wpsip WPS7_PASS=mypassword python fire.py
</code>

to fire an x-ray (ie when the sensor is armed.  wpsip is something like 192.168.0.1

Note: you can also set these environment variables in files like .bashrc so you don't have to type them for each command

I recommend you use a hard wired ethernet line and have a way to cut power to the switch remotely if it fails.  I do this by running an extension cord across the room so that it can be be pulled in event of WPS7 failure (stuck switch, etc).

TODO: use WPS7 scripting capability to make switch throws atomic

=Calibration=

Takes raw, uncalibrated images.  I've been asked a few times if I could provide calibration files for the Windows driver or could even use their calibration files on my driver.  However, I'm not really interested in supporting their proprietary format. If someone submits a patch though I'll probably merge it in.

==cal.py flow==

Quick scheme to get rid of the worst artifacts

Basic idea:

#Capture a dark field frame (no x-ray) to get the lowest possible pixel value
#Capture a flat field frame (x-ray with no object) to get the highest possible pixel value
#Rescale images to range found above

Notes:

*Decoded images invert pixel values (per x-ray industry convention), so high and low are relative
*As of late 2017 capture.py now spits out a sensor .json file with each image. Hopefully the scanner will add this soon as well
*As of this writing no bad pixel replacement is done


===1: Capture dark field===

First, take a dark field capture using something like:

  $ gxs700-capture -f -e

This should yield a raw picture that looks something like this:

[[File:mcmaster_gxs700_foss_df.jpg|300 px]]

And histogram equalized looks like this:

[[File:mcmaster_gxs700_foss_dfe.jpg|300 px]]


===2: Capture flat field===

Now make sure the sensor and the x-ray head have the exact same position and settings you will use to take your actual image capture. Make sure there is nothing in the beam and do a standard capture (and also firing the x-ray head):

  $ gxs700-capture -e

This produces a flat field image like this:

[[File:mcmaster_gxs700_foss_ff.jpg|300 px]]

Which might look like this when histogram equalized:

[[File:mcmaster_gxs700_foss_ffe.jpg|300 px]]

For best results you should also let the sensor and x-ray head sit a while to warm up. I'm not sure how long matters, but maybe 10 minutes would be good


===3: Capture data===

ie using capture.py or xray_plan_cli.py

Put your sample in and use the exact setup as the flat field to capture data. Don't move the sensor or x-ray head


===4: Correct images===

run something like

  $ python cal.py  df.png ff.png png cal

Where:

*df.png is your dark field capture
*ff.png is your flat field capture
*png is a directory with your images to be corrected
*cal is the output directory with corrected images

Here is a raw image as captured:


[[File:mcmaster_gxs700_foss_ex_raw.jpg|300 px]]

And with histogram equalization:

[[File:mcmaster_gxs700_foss_ex_raw_e.jpg|300 px]]

Now the corrected image:

[[File:mcmaster_gxs700_foss_ex_out.jpg|300 px]]

And it with histogram equalization:

[[File:mcmaster_gxs700_foss_ex_out_e.jpg|300 px]]

=Quality=

I haven't played around too much with trying to maximize quality.  One thing that's clear though is that the sensor should be as close as possible to the object to be x-rayed.  The tube to sample distance doesn't seem to matter as much

=Stitching=

stitch.sh has an example workflow using pr0ntools (panotools).  At the core its using mask.py to generate transparency masked images to use the full, albeit irregular, sensor area.