finalize README.md + example + cython interface

README.md

@@ -113,12 +113,14 @@ component, text field or buffer.
 
 ## Installation
 
+The _IMCtermite_ library may be employed both as a _CLI_ tool and a _python_
+module.
+
 ### CLI tool
 
-The _IMCtermite_ library may be employed both as a _CLI_ tool and a _python_
+To build the CLI tool locally use the default target `make`  resulting
-module. To build the CLI tool locally use the default target `make`  resulting
+in the binary `imctermite`. To ensure system-wide availability the installation
-in the binary `imctermite` while the installation of it in the location
+of the tool (in the default location `/usr/local/bin`) is done via
-`/usr/local/bin` is done via
 
 ```
 make install
@@ -168,4 +170,33 @@ the `--output` option.
 
 ### Python
 
+Given the `imctermite` module is available we can import it and declare an instance
+of it by passing a _raw_ file to the constructor
+
+```Python
+import imc_termite
+
+imcraw = imc_termite.imctermite(b"sample/sampleA.raw")
+```
+
+An example of how to create an instance and obtain the list of channels is:
+
+```Python
+import imc_termite
+
+# declare and initialize instance of "imctermite" by passing a raw-file
+try :
+    imcraw = imc_termite.imctermite(b"samples/sampleA.raw")
+except RuntimeError as e :
+    print("failed to load/parse raw-file: " + str(e))
+
+# obtain list of channels as list of dictionaries (without data)
+channels = imcraw.get_channels(False)
+print(channels)
+```
+
+A more complete example including the methods for obtaining the channels including
+their data and or directly printing them to files can be found at
+[Usage](python/usage.py).
+
 ## References

cython/imc_termite.pxd

@@ -11,8 +11,8 @@ cdef extern from "imc_raw.hpp" namespace "imc":
     imc_termite() except +
     imc_termite(string rawfile) except +
     # provide raw file
-    void submit_file(string rawfile) except+
+    void set_file(string rawfile) except +
     # get JSON list of channels
-    vector[string] get_channels() except+
+    vector[string] get_channels(bool json, bool data) except +
     # print all channels
     void print_channels(string outputdir) except +

cython/py_imc_termite.pyx

@@ -16,12 +16,14 @@ cdef class imctermite:
 
   # provide raw file
   def submit_file(self,string rawfile):
-    self.cpp_tdm.set_file(rawfile)
+    self.cpp_imc.set_file(rawfile)
 
   # get JSON list of channels
   def get_channels(self, bool data):
-    return self.cpp_imc.get_channels()
+    chnlst = self.cpp_imc.get_channels(True,data)
+    chnlstjn = [jn.loads(chn.decode()) for chn in chnlst]
+    return chnlstjn
 
   # print a channels
-  def print_channel(self, string outputdir):
+  def print_channels(self, string outputdir):
-    self.cpp_tdm.print_channels(outputdir)
+    self.cpp_imc.print_channels(outputdir)

cython/setup.py

@@ -20,5 +20,5 @@ setup(
     author_email='mario.fink@record-evolution.de',
     url='https://github.com/RecordEvolution/IMCtermite.git',
     name="imc_termite",
-    ext_modules=cythonize(extensions)
+    ext_modules=cythonize(extensions,force=True)
 )

lib/imc_channel.hpp

@@ -364,11 +364,11 @@ namespace imc
                                <<"\",\"comment\":\""<<group_comment_<<"\""<<"}";
       if ( include_data )
       {
-        ss<<"\",\"ydata\":\""<<imc::joinvec<imc::datatype>(ydata_,0)
+        ss<<",\"ydata\":"<<imc::joinvec<imc::datatype>(ydata_,0)
-          <<"\",\"xdata\":\""<<imc::joinvec<double>(xdata_,0);
+          <<",\"xdata\":"<<imc::joinvec<double>(xdata_,0);
       }
       // ss<<"\",\"aff. blocks\":\""<<chnenv_.get_json()
-      ss<<"\"}";
+      ss<<"}";
 
       return ss.str();
     }

makefile

@@ -63,14 +63,14 @@ docker-run:
 
 cython-build : $(CYT)setup.py $(CYT)imc_termite.pxd $(CYT)py_imc_termite.pyx $(HPP)
 	python3 $< build_ext --inplace
-	cp -v imc_termite_cpython-*.so $(PYT)
+	cp -v imc_termite.cpython-*.so $(PYT)
 
 cython-install : $(CYT)setup.py $(CYT)imc_termite.pxd $(CYT)py_imc_termite.pyx $(HPP)
 	python3 $< install --record files_imctermite.txt
 
 cython-clean :
-	rm -vf imc_termite_cpython-*.so
+	rm -vf imc_termite.cpython-*.so
-	rm -vf $(PYT)imc_termite_cpython-*.so
+	rm -vf $(PYT)imc_termite.cpython-*.so
 
 #-----------------------------------------------------------------------------#
 # Python (to be removed)

python/usage.py

@@ -0,0 +1,25 @@
+
+import imc_termite
+import json
+
+# declare and initialize instance of "imctermite" by passing a raw-file
+try :
+    imcraw = imc_termite.imctermite(b"samples/sampleA.raw")
+except RuntimeError as e :
+    print("failed to load/parse raw-file: " + str(e))
+
+# obtain list of channels as list of dictionaries (without data)
+channels = imcraw.get_channels(False)
+print(json.dumps(channels,indent=4, sort_keys=False))
+
+# obtain data of first channel (with data)
+channelsdata = imcraw.get_channels(True)
+if len(channelsdata) > 0 :
+    chnydata = channelsdata[0]['ydata']
+    chnxdata = channelsdata[0]['xdata']
+
+print(len(chnydata))
+print(len(chnxdata))
+
+# print the channels into a specific directory
+imcraw.print_channels(b"./")