1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
|
=======
Filters
=======
Filters transform data and have at least one input and one output.
Point-based transformation
==========================
Binarization
------------
.. gobj:class:: binarize
Binarizes an image.
.. gobj:prop:: threshold:float
Any values above the threshold are set to one all others to zero.
Clipping
--------
.. gobj:class:: clip
Clip input to set minimum and maximum value.
.. gobj:prop:: min:float
Minimum value, all values lower than `min` are set to `min`.
.. gobj:prop:: max:float
Maximum value, all values higher than `max` are set to `max`.
Masking
-------
.. gobj:class:: mask
Mask the circular outer region by setting values to zero.
Arithmetic expressions
----------------------
.. gobj:class:: calculate
Calculate an arithmetic expression. You have access to the value stored in
the input buffer via the *v* letter in :gobj:prop:`expression` and to the
index of *v* via letter *x*. Please be aware that *v* is a floating point
number while *x* is an integer. This is useful if you have multidimensional
data and want to address only one dimension. Let's say the input is two
dimensional, 256 pixels wide and you want to fill the x-coordinate with *x*
for all respective y-coordinates (a gradient in x-direction). Then you can
write *expression="x % 256"*. Another example is the *sinc* function which
you would calculate as *expression="sin(v) / x"* for 1D input.
For more complex math or other operations please consider using
:ref:`OpenCL <generic-opencl-ref>`.
.. gobj:prop:: expression:string
Arithmetic expression with math functions supported by OpenCL.
Statistics
----------
.. gobj:class:: measure
Measure basic image properties.
.. gobj:prop:: metric:string
Metric, one of ``min``, ``max``, ``sum``, ``mean``, ``var``, ``std``,
``skew`` or ``kurtosis``.
.. gobj:prop:: axis:int
Along which axis to measure (-1, all).
.. _generic-opencl-ref:
Generic OpenCL
--------------
.. gobj:class:: opencl
Load an arbitrary OpenCL :gobj:prop:`kernel` from :gobj:prop:`filename` or
:gobj:prop:`source` and execute it on each input. The kernel must accept as
many global float array parameters as connected to the filter and one
additional as an output. For example, to compute the difference between two
images, the kernel would look like::
kernel void difference (global float *a, global float *b, global float *c)
{
size_t idx = get_global_id (1) * get_global_size (0) + get_global_id (0);
c[idx] = a[idx] - b[idx];
}
and could be used like so if defined in a file named ``diff.cl``::
$ ufo-launch [read, read] ! opencl kernel=difference filename=diff.cl ! null
If :gobj:prop:`filename` is not set, a default kernel file (``opencl.cl``)
is loaded. See :ref:`opencl-default-kernels` for a list of kernel names
defined in that file.
.. gobj:prop:: filename:string
Filename with kernel sources to load.
.. gobj:prop:: source:string
String with OpenCL kernel code.
.. gobj:prop:: kernel:string
Name of the kernel that this filter is associated with.
.. gobj:prop:: options:string
OpenCL build options.
.. gobj:prop:: dimensions:uint
Number of dimensions the kernel works on. Must be in [1, 3].
Spatial transformation
======================
Transposition
-------------
.. gobj:class:: transpose
Transpose images from (x, y) to (y, x).
Rotation
--------
.. gobj:class:: rotate
Rotates images clockwise by an :gobj:prop:`angle` around a :gobj:prop:`center`
(x, y). When :gobj:prop:`reshape` is ``True``, the rotated image is not
cropped, i.e. the output image size can be larger that the input size.
Moreover, this mode makes sure that the original coordinates of the input are
all contained in the output so that it is easier to see the rotation in the
output. Try e.g. rotation with :gobj:prop:`center` equal to :math:`(0, 0)` and
angle :math:`\pi / 2`.
.. gobj:prop:: angle:float
Rotation angle in radians.
.. gobj:prop:: reshape:boolean
Reshape the result to encompass the complete input image and input
indices.
.. gobj:prop:: center:GValueArray
Center of rotation (x, y)
.. gobj:prop:: addressing-mode:enum
Addressing mode specifies the behavior for pixels falling outside the
original image. See OpenCL ``sampler_t`` documentation for more information.
.. gobj:prop:: interpolation:enum
Specifies interpolation when a computed pixel coordinate falls between
pixels, can be `nearest` or `linear`.
Flipping
--------
.. gobj:class:: flip
Flips images vertically or horizontally.
.. gobj:prop:: direction:enum
Can be either `horizontal` or `vertical` and denotes the direction along
with the image is flipped.
Binning
-------
.. gobj:class:: bin
Bin a square of pixels by summing their values.
.. gobj:prop:: size:uint
Number of pixels in one direction to bin to a single pixel value.
Rescaling
---------
.. gobj:class:: rescale
Rescale input data by a fixed :gobj:prop:`factor`.
.. gobj:prop:: factor:float
Fixed factor for scaling the input in both directions.
.. gobj:prop:: x-factor:float
Fixed factor for scaling the input width.
.. gobj:prop:: y-factor:float
Fixed factor for scaling the input height.
.. gobj:prop:: width:uint
Fixed width, disabling scalar rescaling.
.. gobj:prop:: height:uint
Fixed height, disabling scalar rescaling.
.. gobj:prop:: interpolation:enum
Interpolation method used for rescaling which can be either ``nearest`` or ``linear``.
Padding
-------
.. gobj:class:: pad
Pad an image to some extent with specific behavior for pixels falling
outside the original image.
.. gobj:prop:: x:int
Horizontal coordinate in the output image which will contain the first
input column.
.. gobj:prop:: y:int
Vertical coordinate in the output image which will contain the first
input row.
.. gobj:prop:: width:uint
Width of the padded image.
.. gobj:prop:: height:uint
Height of the padded image.
.. gobj:prop:: addressing-mode:enum
Addressing mode specifies the behavior for pixels falling outside the
original image. See OpenCL ``sampler_t`` documentation for more information.
Cropping
--------
.. gobj:class:: crop
Crop a region of interest from two-dimensional input. If the region is
(partially) outside the input, only accessible data will be copied.
.. gobj:prop:: x:uint
Horizontal coordinate from where to start the ROI.
.. gobj:prop:: y:uint
Vertical coordinate from where to start the ROI.
.. gobj:prop:: width:uint
Width of the region of interest.
.. gobj:prop:: height:uint
Height of the region of interest.
.. gobj:prop:: from-center:boolean
Start cropping from the center outwards.
Cutting
-------
.. gobj:class:: cut
Cuts a region from the input and merges the two halves together. In a way,
it is the opposite of crop.
.. gobj:prop:: width:uint
Width of the region to cut out.
Tiling
------
.. gobj:class:: tile
Cuts input into multiple tiles. The stream contains tiles in a zig-zag
pattern, i.e. the first tile starts at the top left corner of the input goes
on the same row until the end and continues on the first tile of the next
row until the final tile in the lower right corner.
.. gobj:prop:: width:uint
Width of a tile which must be a divisor of the input width. If this is
not changed, the full width will be used.
.. gobj:prop:: height:uint
Width of a tile which must be a divisor of the input height. If this is
not changed, the full height will be used.
Swapping quadrants
------------------
.. gobj:class:: swap-quadrants
Cuts the input into four quadrants and swaps the lower right with the upper
left and the lower left with the upper right quadrant.
Polar transformation
--------------------
.. gobj:class:: polar-coordinates
Transformation between polar and cartesian coordinate systems.
When transforming from cartesian to polar coordinates the origin is in the
image center (:gobj:prop:`width` / 2, :gobj:prop:`height` / 2). When
transforming from polar to cartesian coordinates the origin is in the image
corner (0, 0).
.. gobj:prop:: width:uint
Final width after transformation.
.. gobj:prop:: height:uint
Final height after transformation.
.. gobj:prop:: direction: string
Conversion direction from ``polar_to_cartesian``.
Stitching
---------
.. gobj:class:: stitch
Stitches two images horizontally based on their relative given
:gobj:prop:`shift`, which indicates how much is the second image shifted
with respect to the first one, i.e. there is an overlapping region given by
:math:`first\_width - shift`. First image is inserted to the stitched image
from its left edge and the second image is inserted after the overlapping
region. If shift is negative, the two images are swapped and stitched as
described above with shift made positive.
If you are stitching a 360-degree off-centered tomographic data set and
know the axis of rotation, shift can be computed as :math:`2axis -
second\_width` for the case the axis of rotation is greater than half of the
first image. If it is less, then the shift is :math:`first\_width - 2 axis`.
Moreover, you need to horizontally flip one of the images because this task
expects images which can be stitched directly, without additional needed
transformations.
Stitching requires two inputs. If you want to stitch a 360-degree
off-centered tomographic data set you can use:
.. code-block:: bash
ufo-launch [read path=projections_left/, read path=projections_right/ ! flip direction=horizontal] ! stitch shift=N ! write filename=foo.tif
.. gobj:prop:: shift:int
How much is second image shifted with respect to the first one. For
example, shift 0 means that both images overlap perfectly and the
stitching doesn't actually broaden the image. Shift corresponding to
image width makes for a stitched image with twice the width of the
respective images (if they have equal width).
.. gobj:prop:: adjust-mean:boolean
Compute the mean of the overlapping region in the two images and adjust
the second image to match the mean of the first one.
.. gobj:prop:: blend:boolean
Linearly interpolate between the two images in the overlapping region.
Multi-stream
============
Interpolation
-------------
.. gobj:class:: interpolate
Interpolates incoming data from two compatible streams, i.e. the task
computes :math:`(1 - \alpha) s_1 + \alpha s_2` where :math:`s_1` and
:math:`s_2` are the two input streams and :math:`\alpha` a blend factor.
:math:`\alpha` is :math:`i / (n - 1)` for :math:`n > 1`, :math:`n` being
:gobj:prop:`number` and :math:`i` the current iteration.
.. gobj:prop:: number:uint
Number of total output stream length.
.. gobj:class:: interpolate-stream
Interpolates between elements from an incoming stream.
.. gobj:prop:: number:uint
Number of total output stream length.
Subtract
--------
.. gobj:class:: subtract
Subtract data items of the second from the first stream.
Correlate
---------
.. gobj:class:: correlate-stacks
Reads two datastreams, the first must provide a 3D stack of images that is
used to correlate individal 2D images from the second datastream. The
``number`` property must contain the expected number of items in the second
stream.
.. gobj:prop:: number:uint
Number of data items in the second data stream.
Filters
=======
Median
------
.. gobj:class:: median-filter
Filters input with a simple median.
.. gobj:prop:: size:uint
Odd-numbered size of the neighbouring window.
Edge detection
--------------
.. gobj:class:: detect-edge
Detect edges by computing the power gradient image using different edge
filters.
.. gobj:prop:: filter:enum
Edge filter (or operator) which is one of ``sobel``, ``laplace`` and
``prewitt``. By default, the ``sobel`` operator is used.
Gaussian blur
-------------
.. gobj:class:: blur
Blur image with a gaussian kernel.
.. gobj:prop:: size:uint
Size of the kernel.
.. gobj:prop:: sigma:float
Sigma of the kernel.
Gradient
--------
.. gobj:class:: gradient
Compute gradient.
.. gobj:prop:: direction:enum
Direction of the gradient, can be either ``horizontal``, ``vertical``,
``both`` or ``both_abs``.
Non-local-means denoising
-------------------------
.. gobj:class:: non-local-means
Reduce noise using Buades' non-local means algorithm.
.. gobj:prop:: search-radius:uint
Radius for similarity search.
.. gobj:prop:: patch-radius:uint
Radius of patches.
.. gobj:prop:: h:float
Smoothing control parameter, should be around noise standard deviation
or slightly less. Higher h results in a smoother image but with blurred
features. If it is 0, estimate noise standard deviation and use it as
the parameter value.
.. gobj:prop:: sigma:float
Noise standard deviation, improves weights computation. If it is zero,
it is *not* automatically estimated as opposed to :gobj:prop:`h`.
:gobj:prop:`estimate-sigma` has to be specified in order to override
:gobj:prop:`sigma` value.
.. gobj:prop:: window:boolean
Apply Gaussian profile with :math:`\sigma = \frac{P}{2}`, where :math:`P`
is the :gobj:prop:`patch-radius` parameter to the weight computation
which decreases the influence of pixels towards the corners of the
patches.
.. gobj:prop:: fast:boolean
Use a fast version of the algorithm described in [#]_. The only
difference in the result from the classical algorithm is that there is
no Gaussian profile used and from the nature of the fast algorithm,
floating point precision errors might occur for large images.
.. gobj:prop:: estimate-sigma:boolean
Estimate sigma based on [#]_, which overrides :gobj:prop:`sigma`
parameter value. Only the first image in a sequence is used for
estimation and the estimated sigma is re-used for every consequent
image.
.. gobj:prop:: addressing-mode:enum
Addressing mode specifies the behavior for pixels falling outside the
original image. See OpenCL ``sampler_t`` documentation for more information.
.. [#]
J. Darbon, A. Cunha, T.F. Chan, S. Osher, and G.J. Jensen, *Fast
nonlocal filtering applied to electron cryomicroscopy* in 5th IEEE
International Symposium on Biomedical Imaging: From Nano to Macro,
2008, pp. 1331-1334. DOI:10.1109/ISBI.2008.4541250
.. [#]
J. Immerkaer, *Fast noise variance estimation* in Computer vision and image
understanding 64.2 (1996): 300-302. DOI:10.1006/cviu.1996.0060
Finding large spots
-------------------
.. gobj:class:: find-large-spots
Find large spots with extreme values in an image. First, pixels with values
greater than :gobj:prop:`spot_threshold` are added to the mask, then
connected pixels with absolute difference between them and the originally
detected greater than :gobj:prop:`grow-threshold` are added to the mask. In
the end, holes are also removed from the mask.
.. gobj:prop:: spot-threshold:float
Pixels with values greater than this threshold are added to the mask.
.. gobj:prop:: grow-threshold:float
Pixels connected to the ones found by :gobj:prop:`spot-threshold` with
absolute difference greater than this threshold are added to the mask.
If the value is 0, it is automatically set to full width at tenth
maximum of the estimated noise standard deviation.
.. gobj:prop:: addressing-mode:enum
Addressing mode specifies the behavior for pixels falling outside the
original image. See OpenCL ``sampler_t`` documentation for more
information. This parameter is used only for automatic noise standard
deviation estimation.
Horizontal interpolation
------------------------
.. gobj:class:: horizontal-interpolate
Interpolate masked values in rows of an image. For all pixels equal to one
in the mask, find the closest pixel where mask is zero to the left and right
and linearly interpolate the value in the current pixel based on the found
left and right values. If the mask goes to the left or right border of the
image and on the other side there are at least two non-masked pixels
:math:`x_1` and :math:`x_2`, compute the value in the current pixel
:math:`x` by (in case the mask goes to the right border, left is analogous)
:math:`f(x) = f(x_2) + (x - x_2) * (f(x_2) - f(x_1))`. In case there is only
one valid pixel on one of the borders and all the others are masked, use
that pixel's value in all the remaining ones.
Stream transformations
======================
Averaging
---------
.. gobj:class:: average
Read in full data stream and generate an averaged output.
.. gobj:prop:: number:uint
Number of averaged images to output. By default one image is generated.
Reducing with OpenCL
--------------------
.. gobj:class:: opencl-reduce
Reduces or folds the input stream using a generic OpenCL kernel by loading
an arbitrary :gobj:prop:`kernel` from :gobj:prop:`filename` or
:gobj:prop:`source`. The kernel must accept exactly two global float arrays,
one for the input and one for the output. Additionally a second
:gobj:prop:`finish` kernel can be specified which is called once when the
processing finished. This kernel must have two arguments as well, the global
float array and an unsigned integer count. Folding (i.e. setting the initial
data to a known value) is enabled by setting the :gobj:prop:`fold-value`.
Here is an OpenCL example how to compute the average::
kernel void sum (global float *in, global float *out)
{
size_t idx = get_global_id (1) * get_global_size (0) + get_global_id (0);
out[idx] += in[idx];
}
kernel void divide (global float *out, uint count)
{
size_t idx = get_global_id (1) * get_global_size (0) + get_global_id (0);
out[idx] /= count;
}
And this is how you would use it with ``ufo-launch``::
ufo-launch ... ! opencl-reduce kernel=sum finish=divide ! ...
If :gobj:prop:`filename` is not set, a default kernel file is loaded. See
:ref:`opencl-reduction-default-kernels` for a list of possible kernels.
.. gobj:prop:: filename:string
Filename with kernel sources to load.
.. gobj:prop:: source:string
String with OpenCL kernel code.
.. gobj:prop:: kernel:string
Name of the kernel that is called on each iteration. Must have two
global float array arguments, the first being the input, the second the
output.
.. gobj:prop:: finish:string
Name of the kernel that is called at the end after all iterations. Must
have a global float array and an unsigned integer arguments, the first
being the data, the second the iteration counter.
.. gobj:prop:: fold-value:float
If given, the initial data is filled with this value, otherwise the
first input element is used.
.. gobj:prop:: dimensions:uint
Number of dimensions the kernel works on. Must be in [1, 3].
Statistics
----------
.. gobj:class:: flatten
Flatten input stream by reducing with operation based on the given mode.
.. gobj:prop:: mode:string
Operation, can be either ``min``, ``max``, ``sum`` and ``median``.
.. gobj:class:: flatten-inplace
Faster inplace operating variant of the ``flatten`` task.
.. gobj:prop:: mode:enum
Operation, can be either ``min``, ``max`` and ``sum``.
Slicing
-------
.. gobj:class:: slice
Slices a three-dimensional input buffer to two-dimensional slices.
Stacking
--------
.. gobj:class:: stack
Symmetrical to the slice filter, the stack filter stacks two-dimensional
input.
.. gobj:prop:: number:uint
Number of items, i.e. the length of the third dimension.
Stacking with sliding window
----------------------------
.. gobj:class:: sliding-stack
Stacks input images up to the specified :gobj:prop:`number` and then
replaces old images with incoming new ones as they come. The first image is
copied to all positions in the beginning. By default, images in the window
are not ordered, i.e. if e.g. :gobj:prop:`number` = 3, then the window will
contain the following input images: (0, 0, 0), (0, 1, 0), (0, 1, 2), (3, 1,
2), (3, 4, 2), (3, 4, 5) and so on. If you want them to appear ordered with
respect to their arrival time, use :gobj:prop:`ordered`.
.. gobj:prop:: number:uint
Number of items, i.e. the length of the third dimension.
.. gobj:prop:: ordered:boolean
Order items in the sliding window.
Merging
-------
.. gobj:class:: merge
Merges the data from two or more input data streams into a single data
stream by concatenation.
.. gobj:prop:: number:uint
Number of input streams. By default this is two.
Slice mapping
-------------
.. gobj:class:: map-slice
Lays out input images on a quadratic grid. If the :gobj:prop:`number` of
input elements is not the square of some integer value, the next higher
number is chosen and the remaining data is blackened.
.. gobj:prop:: number:uint
Number of expected input elements. If more elements are sent to the
mapper, warnings are issued.
Color mapping
-------------
.. gobj:class:: map-color
Receives a two-dimensional image and maps its gray values to three red,
green and blue color channels using the Viridis color map.
Splitting channels
------------------
.. gobj:class:: unsplit
Turns a three-dimensional image into two-dimensional image by interleaving
the third dimension, i.e. [[[XXX],[YYY],[ZZZ]]] is turned into
[[XYZ],[XYZ],[XYZ]]. This is useful to merge a separate multi-channel RGB
image into a "regular" RGB image that can be shown with ``cv-show``.
This task adds the ``channels`` key to the output buffer containing the
original depth of the input buffer.
Fourier domain
==============
Fast Fourier transform
----------------------
.. gobj:class:: fft
Compute the Fourier spectrum of input data. If :gobj:prop:`dimensions` is one
but the input data is 2-dimensional, the 1-D FFT is computed for each row.
.. gobj:prop:: auto-zeropadding:boolean
Automatically zeropad input data to a size to the next power of 2.
.. gobj:prop:: dimensions:uint
Number of dimensions in [1, 3].
.. gobj:prop:: size-x:uint
Size of FFT transform in x-direction.
.. gobj:prop:: size-y:uint
Size of FFT transform in y-direction.
.. gobj:prop:: size-z:uint
Size of FFT transform in z-direction.
.. gobj:class:: ifft
Compute the inverse Fourier of spectral input data. If
:gobj:prop:`dimensions` is one but the input data is 2-dimensional, the 1-D
FFT is computed for each row.
.. gobj:prop:: dimensions:uint
Number of dimensions in [1, 3].
.. gobj:prop:: crop-width:int
Width to crop output.
.. gobj:prop:: crop-height:int
Height to crop output.
.. gobj:class:: power-spectrum
Compute power spectrum from fourier coefficients.
Frequency filtering
-------------------
.. gobj:class:: filter
Computes a frequency filter function and multiplies it with its input,
effectively attenuating certain frequencies.
.. gobj:prop:: filter :enum
Any of ``ramp``, ``ramp-fromreal``, ``butterworth``, ``faris-byer``,
``hamming`` and ``bh3`` (Blackman-Harris-3). The default filter is
``ramp-fromreal`` which computes a correct ramp filter avoiding offset
issues encountered with naive implementations.
.. gobj:prop:: scale:float
Arbitrary scale that is multiplied to each frequency component.
.. gobj:prop:: cutoff:float
Cutoff frequency of the Butterworth filter.
.. gobj:prop:: order:float
Order of the Butterworth filter.
.. gobj:prop:: tau:float
Tau parameter of Faris-Byer filter.
.. gobj:prop:: theta:float
Theta parameter of Faris-Byer filter.
Stripe filtering
----------------
.. gobj:class:: filter-stripes
Filter vertical stripes. The input and output are in 2D frequency domain.
The filter multiplies horizontal frequencies (for frequency ky=0) with a
Gaussian profile centered at 0 frequency if ``vertical-sigma`` is 0.
Otherwise it applies also a vertical Gaussian profile (1 - Gaussian), which
enables filtering of not perfectly vertical stripes, which is useful for
broader stripes and stripes which are not perfectly straight.
Example usage::
$ ufo-launch read path=sino.tif ! fft dimensions=2 ! filter-stripes sigma=1 ! ifft dimensions=2 ! write filename=sino-filtered.tif
.. gobj:prop:: horizontal-sigma:float
Horizontal filter strength, which is the sigma of the Gaussian. Small
values, e.g. 1e-7 cause only the zero frequency to remain in the
signal, i.e. stronger filtering. Values around 1 are a good starting
point.
.. gobj:prop:: vertical-sigma:float
Vertical filter strength, which is the sigma of the Gaussian. The larger
the value, the more non-vertical frequencies are removed. Value around 4
is a good starting point.
1D stripe filtering
-------------------
.. gobj:class:: filter-stripes1d
Filter stripes in 1D along the x-axis. The input and output are in frequency
domain. The filter multiplies the frequencies with an inverse Gaussian
profile centered at 0 frequency. The inversed profile means that the filter
is f(k) = 1 - gauss(k) in order to suppress the low frequencies.
.. gobj:prop:: strength:float
Filter strength, which is the full width at half maximum of the
gaussian.
Zeropadding
-----------
.. gobj:class:: zeropad
Add zeros in the center of sinogram using :gobj:prop:`oversampling`
to manage the amount of zeros which will be added.
.. gobj:prop:: oversampling:uint
Oversampling coefficient.
.. gobj:prop:: center-of-rotation:float
Center of rotation of sample.
Reconstruction
==============
Flat-field correction
---------------------
.. gobj:class:: flat-field-correct
Computes the flat field correction using three data streams:
1. Projection data on input 0
2. Dark field data on input 1
3. Flat field data on input 2
.. gobj:prop:: absorption-correct:boolean
If *TRUE*, compute the negative natural logarithm of the
flat-corrected data.
.. gobj:prop:: fix-nan-and-inf:boolean
If *TRUE*, replace all resulting NANs and INFs with zeros.
.. gobj:prop:: sinogram-input:boolean
If *TRUE*, correct only one line (the sinogram), thus darks are flats are 1D.
.. gobj:prop:: dark-scale:float
Scale the dark field prior to the flat field correct.
.. gobj:prop:: flat-scale:float
Scale the flat field prior to the flat field correct.
Sinogram transposition
----------------------
.. gobj:class:: transpose-projections
Read a stream of two-dimensional projections and output a stream of
transposed sinograms. :gobj:prop:`number` *must* be set to the
number of incoming projections to allocate enough memory.
.. gobj:prop:: number:uint
Number of projections.
.. Warning::
This is a memory intensive task and can easily exhaust your
system memory. Make sure you have enough memory, otherwise the process
will be killed.
Tomographic backprojection
--------------------------
.. gobj:class:: backproject
Computes the backprojection for a single sinogram.
.. gobj:prop:: num-projections:uint
Number of projections between 0 and 180 degrees.
.. gobj:prop:: offset:uint
Offset to the first projection.
.. gobj:prop:: axis-pos:double
Position of the rotation axis in horizontal pixel dimension of a
sinogram or projection. If not given, the center of the sinogram is
assumed.
.. gobj:prop:: angle-step:double
Angle step increment in radians. If not given, pi divided by height
of input sinogram is assumed.
.. gobj:prop:: angle-offset:double
Constant angle offset in radians. This determines effectively the
starting angle.
.. gobj:prop:: mode:enum
Reconstruction mode which can be either ``nearest`` or ``texture``.
.. gobj:prop:: roi-x:uint
Horizontal coordinate of the start of the ROI. By default 0.
.. gobj:prop:: roi-y:uint
Vertical coordinate of the start of the ROI. By default 0.
.. gobj:prop:: roi-width:uint
Width of the region of interest. The default value of 0 denotes full
width.
.. gobj:prop:: roi-height:uint
Height of the region of interest. The default value of 0 denotes full
height.
Forward projection
------------------
.. gobj:class:: forwardproject
Computes the forward projection of slices into sinograms.
.. gobj:prop:: number:uint
Number of final 1D projections, that means height of the sinogram.
.. gobj:prop:: angle-step:float
Angular step between two adjacent projections. If not changed, it is
simply pi divided by :gobj:prop:`number`.
Laminographic backprojection
----------------------------
.. gobj:class:: lamino-backproject
Backprojects parallel beam computed laminography projection-by-projection
into a 3D volume.
.. gobj:prop:: region-values:int
Elements in regions.
.. gobj:prop:: float-region-values:float
Elements in float regions.
.. gobj:prop:: x-region:GValueArray
X region for reconstruction as (from, to, step).
.. gobj:prop:: y-region:GValueArray
Y region for reconstruction as (from, to, step).
.. gobj:prop:: z:float
Z coordinate of the reconstructed slice.
.. gobj:prop:: region:GValueArray
Region for the parameter along z-axis as (from, to, step).
.. gobj:prop:: projection-offset:GValueArray
Offset to projection data as (x, y) for the case input data is cropped
to the necessary range of interest.
.. gobj:prop:: center:GValueArray
Center of the volume with respect to projections (x, y), (rotation
axes).
.. gobj:prop:: overall-angle:float
Angle covered by all projections (can be negative for negative steps in
case only num-projections is specified)
.. gobj:prop:: num-projections:uint
Number of projections.
.. gobj:prop:: tomo-angle:float
Tomographic rotation angle in radians (used for acquiring projections).
.. gobj:prop:: lamino-angle:float
Absolute laminogrpahic angle in radians determining the sample tilt.
.. gobj:prop:: roll-angle:float
Sample angular misalignment to the side (roll) in radians (CW is
positive).
.. gobj:prop:: parameter:enum
Which paramter will be varied along the z-axis, from ``z``, ``x-center``,
``lamino-angle``, ``roll-angle``.
Fourier interpolation
---------------------
.. gobj:class:: dfi-sinc
Computes the 2D Fourier spectrum of reconstructed image using 1D Fourier
projection of sinogram (fft filter must be applied before). There are no
default values for properties, therefore they should be assigned manually.
.. gobj:prop:: kernel-size:uint
The length of kernel which will be used in
interpolation.
.. gobj:prop:: number-presampled-values:uint
Number of presampled values which will be used to calculate
``kernel-size`` kernel coefficients.
.. gobj:prop:: roi-size:int
The length of one side of region of Interest.
.. gobj:prop:: angle-step:double
Increment of angle in radians.
Center of rotation
------------------
.. gobj:class:: center-of-rotation
Compute the center of rotation of input sinograms.
.. gobj:prop:: angle-step:double
Step between two successive projections.
.. gobj:prop:: center:double
The calculated center of rotation.
Sinogram offset shift
---------------------
.. gobj:class:: cut-sinogram
Shifts the sinogram given a center not centered to the input image.
.. gobj:prop:: center-of-rotation:float
Center of rotation of specimen.
Phase retrieval
---------------
.. gobj:class:: retrieve-phase
Computes and applies a fourier filter to correct phase-shifted data.
Expects frequencies as an input and produces frequencies as an output.
Propagation distance can be specified for both x and y directions together
by the :gobj:prop:`distance` parameter or separately by
:gobj:prop:`distance-x` and :gobj:prop:`distance-y`, which is useful e.g.
when pixel size is not symmetrical.
.. gobj:prop:: method:enum
Retrieval method which is one of ``tie``, ``ctf``, ``qp`` or ``qp2``.
.. gobj:prop:: energy:float
Energy in keV.
.. gobj:prop:: distance:float
Distance in meters.
.. gobj:prop:: distance-x:float
Distance in x-direction in meters.
.. gobj:prop:: distance-y:float
Distance in y-direction in meters.
.. gobj:prop:: pixel-size:float
Pixel size in meters.
.. gobj:prop:: regularization-rate:float
Regularization parameter is log10 of the constant to be added to the
denominator to regularize the singularity at zero frequency: 1/sin(x) ->
1/(sin(x)+10^-RegPar). It is also log10(delta / beta) where the complex
refractive index is delta + beta * 1j.
Typical values [2, 3].
.. gobj:prop:: thresholding-rate:float
Parameter for Quasiparticle phase retrieval which defines the width of
the rings to be cropped around the zero crossing of the CTF denominator
in Fourier space.
Typical values in [0.01, 0.1], ``qp`` retrieval is rather independent of
cropping width.
.. gobj:prop:: frequency-cutoff:float
Cutoff frequency after which the filter is set to 0 in radians.
.. gobj:prop:: output-filter:boolean
Output filter values instead of the filtered frequencies.
General matrix-matrix multiplication
====================================
.. gobj:class:: gemm
Computes :math:`\alpha A \cdot B + \beta C` where :math:`A`, :math:`B` and :math:`C` are input
streams 0, 1 and 2 respectively. :math:`A` must be of size :math:`m\times k`, :math:`B`
:math:`k\times n` and :math:`C` :math:`m\times n`.
.. note::
This filter is only available if CLBlast support is available.
.. gobj:prop:: alpha:float
Scalar multiplied with :math:`AB`.
.. gobj:prop:: beta:float
Scalar multiplied with :math:`C`.
Segmentation
============
.. gobj:class:: segment
Segments a stack of images given a field of labels using the random walk
algorithm described in [#]_. The first
input stream must contain three-dimensional image stacks, the second input
stream a label image with the same width and height as the images. Any pixel
value other than zero is treated as a label and used to determine segments
in all directions.
.. [#]
Lösel and Heuveline, *Enhancing a Diffusion Algorithm for 4D Image
Segmentation Using Local Information* in Proc. SPIE 9784, Medical
Imaging 2016, http://proceedings.spiedigitallibrary.org/proceeding.aspx?articleid=2506235
Auxiliary
=========
Buffering
---------
.. gobj:class:: buffer
Buffers items internally until data stream has finished. After that all
buffered elements are forwarded to the next task.
.. gobj:prop:: number:uint
Number of pre-allocated buffers.
.. gobj:prop:: dup-count:uint
Number of times each image should be duplicated.
.. gobj:prop:: loop:boolean
Duplicates the data in a loop manner :gobj:prop:`dup-count` times.
Stamp
-----
.. gobj:class:: stamp
Writes the current iteration into the top-left corner.
.. gobj:prop:: font:string
Pango font description, by default set to ``Mono 9``.
.. gobj:prop:: scale:float
Scales the default brightness of 1.0.
.. note::
This filter requires Pango and Cairo for text layouting.
Loops
-----
.. gobj:class:: loop
Repeats output of incoming data items. It uses a low-overhead policy to
avoid unnecessary copies. You can expect the data items to be on the device
where the data originated.
.. gobj:prop:: number:uint
Number of iterations for each received data item.
Monitoring
----------
.. gobj:class:: monitor
Inspects a data stream and prints size, location and associated metadata
keys on stdout.
.. gobj:prop:: print:uint
If set print the given numbers of items on stdout as hexadecimally
formatted numbers.
Sleep
-----
.. gobj:class:: sleep
Wait :gobj:prop:`time` seconds before continuing. Useful for debugging
throughput issues.
.. gobj:prop:: time:double
Time to sleep in seconds.
Display
-------
.. gobj:class:: cv-show
Shows the input using an OpenCV window.
.. gobj:prop:: min:float
Minimum for display value scaling. If not set, will be determined at
run-time.
.. gobj:prop:: max:float
Maximum for display value scaling. If not set, will be determined at
run-time.
|