Metadata-Version: 2.1
Name: IMCtermite
Version: 1.2.0
Summary: Enables extraction of measurement data from binary files with extension 'raw' used by proprietary software imcFAMOS/imcSTUDIO and facilitates its storage in open source file formats
Home-page: https://github.com/RecordEvolution/IMCtermite.git
Author: Record Evolution GmbH
Author-email: mario.fink@record-evolution.de
Maintainer: Record Evolution GmbH
License: MIT
Project-URL: Bug Tracker, https://github.com/RecordEvolution/IMCtermite/issues
Description: |--------|--------------------------------------------|
        | NO     | origin of data                             |
        | NT     | timestamp of trigger                       |
        | ND     | (color) display properties                 |
        | NU     | user defined key                           |
        | Np     | property of a channel                      |
        | NE     | extraction rule for channels from BUS data |
        
        The format loosely defines some rules for the ordering of the markers in the
        file stream. The rules for critical keys include: _CK_ has to follow up on _CF_,
        _CK_ may be followed by any number of _CG_ blocks, each _CG_ has to be followed
        by (any number of) component sequences comprised of the series _CC_ , _CP_,
        (_CR_), (_ND_) and terminated by either _CS_ or the start of a new group,
        component, text field or buffer.
        
        ## Installation
        
        The _IMCtermite_ library may be employed both as a _CLI_ tool and a _python_
        module.
        
        ### CLI tool
        
        To build the CLI tool locally, use the default target `make` resulting
        in the binary `imctermite`. To ensure system-wide availability, the installation
        of the tool (in the default location `/usr/local/bin`) is done via
        
        ```
        make install
        ````
        
        which may require root permissions.
        
        ### Python
        
        To integrate the library into a customized ETL toolchain, several cython targets
        are available. For a local build that enables you to run the examples, use:
        
        ```
        make cython-build
        ```
        
        However, in a production environment, a proper installation of the module with
        `make cython-install` is recommended for system-wide availability of the module.
        
        ## Usage
        
        ### CLI
        
        The usage of the `imctermite` binary looks like this:
        
        ```
        imctermite <raw-file> [options]
        ```
        
        You have to provide a single _raw_ file and any option to specify what
        to do with the data. All available options can be listed with `imctermite --help`:
        
        ```
        Options:
        
         -c, --listchannels      list channels
         -b, --listblocks        list IMC key-blocks
         -d, --output            output directory to print channels
         -h, --help              show this help message
         -v, --version           display version
        ```
        
        For instance, to show a list of all channels included in `sample-data.raw`, you
        do `imctermite sample-data.raw --listchannels`. No output files are
        written by default. Output files are written only when an existing (!) directory is provided as argument to
        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](python/usage.py), including the methods for obtaining the
        channels, i.a. their data and/or directly printing them to files, can be found
        in the Python folder.
        
        ## References
        
        - https://www.imc-tm.de/produkte/messtechnik-software/imc-famos/funktionen/im-und-export/
        - https://www.imc-tm.de/produkte/messtechnik-hardware/imc-cronosflex/ueberblick/
        - https://cython.readthedocs.io/en/latest/src/userguide/wrapping_CPlusPlus.html
        - https://github.com/Apollo3zehn/ImcFamosFile
        
Keywords: IMC raw imcFAMOS imcSTUDIO imcCRONOS
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
