patch-nx tutorial#

5 min read

the patch-nx application is used to patch an existing NXTomo entry in a nexus file.

For now there is two main ‘features’:

  • adding dark series and / or flatfield series to an existing NXTomo entry

  • modifying frame type (projection, dark, flatfield, projection, alignment, invalid)

Note

You can do both within only one call to the function. In this case we will first update frame type prior to add dark / flatfield series. This choice has been made to avoid confusion on frame indices. And to fit the use case users want to modify dark and / or flat. But a good practice would be to call twice the command.

Adding dark and / or flatfield serie#

This can be used for example if you want to add some dark of flat series as post processing.

Warning

this will modify inplace datasets contained in the target entry. If you wan’t to save original data then you should first copy the file prior to calling this function.

Warning

Any dataset you want to insert must be store into a ‘permanant’ relative position to the file you modify. This is needed to insure virtual dataset consistency. This is also why you should provide urls.

Note

HDF5 virtual dataset are managed by creating a new data set from original sources and adding a new virtual source pointing to the provided url.

To call this application you can call directly

nxtomomill patch-nx [my_file my_entry] [[--darks-at-start url1 --flats-at-dark url2 --darks-at-end url3 --flats-at-end url4]]

Note

urls can be provided two ways:

This is an example on how to add:

  • a serie of dark before projections contained in a dataset name ‘data2’ at the root node of the ‘dark.hdf5’ file

  • a serie of flats between the added dark and the original set of projections contained in the ‘flat’ dataset inside the my_nxtomo.nx file and only picking slices 1 and 2

nxtomomill patch-nx /tmp/tmpzk3v37h_/simple_case/my_nxtomo.nx entry --darks-at-start data2@/tmp/tmpzk3v37h_/dark.hdf5 --flats-at-start silx:///tmp/tmpzk3v37h_/simple_case/simple_case.h5?path=flat&slice=1,2

Modifying frame type#

From the command line you can define a set of frame for which you would like to change the type.

The API to modify frame type is the following:

nxtomomill patch-nx [my_file my_entry] [[--invalid-frames frames1 update-to-projection frames2 --update-to-dark frames3 --update-to-flat frames4 --update-to-alignment frames5]]

Those are some examples of usage:

# force frames 26 and 27 to be dark
nxtomomill patch-nx --update-to-dark 26:28 my_nxtomo.nx entry
# force all projections to be dark
nxtomomill patch-nx --update-to-dark projection my_nxtomo.nx entry
# force frames 10, 13, 16 and 19 to be flatfield
nxtomomill patch-nx --update-to-flat 10:20:3 my_nxtomo.nx entry
# force frame 0, 1 and to 4 to be projections
nxtomomill patch-nx --update-to-proj 0,1,4 my_nxtomo.nx entry
# force first frame to be alignment projection
nxtomomill patch-nx --update-to-alignment 0 my_nxtomo.nx entry
# force all frames to be invalid
nxtomomill patch-nx --invalid-frames : my_nxtomo.nx entry
# force all "projection" frame to be invalid
nxtomomill patch-nx --invalid-frames projection my_nxtomo.nx entry

Note

If you try to modify several frame type at the same type you should know that the order of resolution is: * modify frame to alignment if any * modify frame to projection if any * modify frame to flatfield if any * modify frame to dark type if any * modify frame to invalid if any

Concrete example of modifying flat field on an .nx file#

In this example flat field frames at from acquisition A has been mess up. NXTomo file is name original_acquiA.nx. Entry name is entry000A

And we want to replace them by flat field from acquisition B (master file is acquiB.nx). Entry name is entry000B

This is one way to proceed to replace flat field frames:

  1. go to acquisition A folder containing the acquiA.nx file

    cd [path_to_acquisitionA_folder]/acquisitionA

  2. copy the original .nx file. Modification are in place. This is safer to copy the file.

    cp original_acquiA.nx acquiA.nx

  3. invalidate the flat field frames made at start. In the case let say that we want to invalid frames from 20 to 40 included:

    nxtomomill patch-nx set83_tomo_black_drum_LPJ01_6p5p_20N_0001_0000_patch.nx entry0000 --invalid-frames 20:41

  4. check that the invalidation of frames worked properly using silx view for example

  5. get the silx url you want to link as the new flat field. Syntax is silx://[file_path]?path=[data_path]&slice=[slices] for example here we want to link frames 2000 to 2021 from acquiB.nx So the url looks like: silx://[folder_to_acquiB]/acquiB.nx?path=/entry000B/instrument/detector/data&slices=2000:2021

  6. then patch flat from patch-nx command and the ‘flats-at-start’ option:

    nxtomomill patch-nx acquiA.nx entry000A --flats-at-start "silx://[folder_to_acquiB]/acquiB.nx?path=/entry000B/instrument/detector/data&slices=2000:2021"

    Warning

    when you provide the url make sure you use “ or ‘ characters. Otherwise in this case the command will be executed as a background task and slices will be ignored. It will also try to link it with the full dataset at /entry000B/instrument/detector/data

  7. check that your dataset is complete (using silx view for example)