imaging/getting-started-with-image-streams.md

@@ -204,7 +204,9 @@ See **cv-calc --help --verbose** for details and meanwhile try **cv-calc life**
 ```
 
 # converting images from/to csv
-# image-from-csv
+## image-from-csv
+You may have data, e.g. cartesian 3D points or heatmaps, that you would like to convert into images.
+
 You can create images from [**csv** or binary fixed-width data](https://gitlab.com/orthographic/comma/-/wikis/csv/getting-started:-basic-data-manipulations,-ascii-and-binary-data) where each input record would represent a pixel.
 ```
 > cat <<eof | image-from-csv --fields x,y,r,g,b --output "rows=8;cols=8;type=3ub" | cv-cat "resize=512,512,nearest;view=stay;null"
@@ -225,6 +227,34 @@ For an image stream, specify **block** field (since we are using **view=stay**,
 1,2,3,0,255,255
 eof
 ```
+## image-to-csv
+Rather than performing operations on images, you might need to handle individual pixels, e.g. project them into the 3D space. Use **image-to-csv**, e.g. try:
+```
+> cv-cat --file cat.jpg | image-to-csv | head -n4
+20201120T104314.416482,0,0,49,57,26
+20201120T104314.416482,1,0,50,58,27
+20201120T104314.416482,2,0,47,55,25
+20201120T104314.416482,3,0,48,55,28
+```
+The fields of the output records are: timestamp; x, y pixel coordinates, and RGB channels, if the image is a 3-channel RGB.
+
+As usual, you can specify desired fields, e.g:
+```
+> cv-cat --file cat.jpg | image-to-csv --fields x,y,channels | head -n4
+0,0,49,57,26
+1,0,50,58,27
+2,0,47,55,25
+3,0,48,55,28
+```
+Discard pixels with zero value:
+```
+> cv-cat --file cat.jpg | image-to-csv --fields x,y,channels --discard-zero
+```
+Output binary instead of **csv** ascii (which is 30-50 times faster):
+```
+> cv-cat --file cat.jpg | image-to-csv --fields x,y,channels --discard-zero --binary 2ui,3ub
+```
+For more options, run **image-to-csv --help**.
 
 # links to more (potentially unmaintained) documentation elsewhere:
 - [https://github.com/acfr/snark/wiki/get-started-with-image-data](https://github.com/acfr/snark/wiki/get-started-with-image-data)