# MatSense
[](https://pypi.org/project/MatSense/)
A toolkit that supports both real-time and off-line matrix sensor data processing and 3D visualization.
A typical real-time data flow would be in a client-server manner:
- Matrix sensor data: collected (e.g. by Arduino) and transmitted via a serial port to the computer.
- Data processing: the series of matrix data frames are processed and served by the server.
- Applications: clients connect to server to get processed data and do further work.
Data can also be recorded to and processed from files.
<img src="https://raw.githubusercontent.com/atomiechen/MatSense/main/img/player.png" alt="schematic" width="450" />
3D visualization tools are provided to play real-time stream or recorded data.
## Installation
From PyPI:
```sh
pip install MatSense
```
This will install [Matplotlib](https://matplotlib.org/) to implement 3D visualization tools.
If you want to further try [PyQtGraph](https://www.pyqtgraph.org/) as visualization method:
```sh
pip install MatSense[pyqtgraph]
```
## Usage
### Off-the-shelf tools
3 handy tools are provided. Pass `-h` to get detailed information.
- `matserver` / `python -m matsense.server`
- functions:
- receive data from serial port, process and serve
- process data from file(s) and output to file
- other helpful functions
- supported processing methods:
- voltage-pressure conversion (optional for pressure data)
- spatial filter (in-frame denoising): none, ideal, butterworth, gaussian
- temporal filter (pixel-wise between-frame denoising): none, moving average, rectangular window
- calibration: static or dynamic
- `matclient` / `python -m matsense.client`: receive server data, process and visualize; or control server via interactive commands
- supported processing methods:
- interpolation
- blob parsing
- `matdata` / `python -m matsense.data`: visualize file data, or process off-line data
### Configuration
All 3 tools can be totally configured by a YAML configuration file:
```sh
## server console
matserver --config your_config.yaml
## client console
matclient --config your_config.yaml
## off-line data processing
matdata --config your_config.yaml
```
Priority: commandline arguments > config file > program defaults.
A template YAML configuration (unused options can be set to `~` or removed):
```yaml
## template configurations
## ~ for defaults
## configurations for matserver mode
server_mode:
## enable backend service
service: ~
## enable visualization or not (suppress service)
visualize: ~
## enumerate all serial ports
enumerate: ~
## (suppress serial) simulated data source without actual serial connection
## debug mode: true, false
debug: ~
## (suppress serial) use file as data source or not: true, false
use_file: ~
## configurations for matclient mode
client_mode:
## make client present raw data
raw: ~
## interactive command line mode
interactive: ~
## configurations for matdata mode
data_mode:
## process file data instead of visualization
process: ~
## configurations for file data
data:
## input filename(s), filename or a list of filenames: [a.csv, b.csv, ...]
in_filenames: ~
## output filename, default filename is used when not provided
out_filename: ~
## configurations for matrix sensor
sensor:
## sensor shape: [16, 16], [8, 8], [6, 24]
shape: ~
## total points, can be set to ~
total: ~
## 0/1 mask to exclude non-existent points
## |- for multiline without a newline in the end
mask: ~
## configurations for serial port
serial:
## baudrate: 9600, 250000, 500000, 1000000
baudrate: ~
## serial port timeout, in seconds
timeout: ~
## serial port
port: ~
## data transmission protocol: simple, secure
protocol: ~
## support IMU data
imu: ~
## configurations for client-server connections
connection:
## use UDP or UNIX domain socket
udp: ~
## udp address format: 127.0.0.1:20503
## UNIX deomain socket address format: /var/tmp/unix.socket.server
server_address: ~
client_address: ~
## configurations for data processing
process:
### voltage to the reciprocal of resistance
## reference voltage: 255, 255/3.6*3.3
V0: ~
## constant factor: 1
R0_RECI: ~
## convert voltage to resistance: true
convert: ~
### server data processing
## no filtering and calibration
raw: ~
## time of warming up in seconds: 1
warm_up: ~
## spatial filter: none, ideal, butterworth, gaussian
filter_spatial: ~
## spatial filter cut-off freq: 3.5
filter_spatial_cutoff: ~
## Butterworth filter order: 2
butterworth_order: ~
## temporal filter: none, moving average, rectangular window
filter_temporal: ~
## temporal filter size: 15
filter_temporal_size: ~
## rectangular window filter cut-off frequency: 0.04
rw_cutoff: ~
## calibrative frames, 0 for no calibration: 0, 200
cali_frames: ~
## calibration frame window size, 0 for static and >0 for dynamic: 0, 10000
cali_win_size: ~
## intermediate result: 0, 1, 2
## 0: convert voltage to reciprocal resistance
## 1: convert & spatial filter
## 2: convert & spatial filter & temporal filter
intermediate: ~
### (optional) client data processing
## interpolation shape, default to sensor.shape
interp: ~
## interpolation order: 3
interp_order: ~
## filter out blobs: true
blob: ~
## total blob number: 3
blob_num: ~
## blob filter threshole: 0.1, 0.15
threshold: ~
## special check for certain hardwares: false
special_check: ~
pointing:
## value bound for checking cursor moving state: 0
bound: ~
## directly map coordinates or relatively (suppress trackpoint)
direct_map: ~
## use ThinkPad's TrackPoint (red dot) control style
trackpoint: ~
## smoothing
alpha: ~
## configurations for visualization
visual:
## using pyqtgraph or matplotlib
pyqtgraph: ~
## z-axis limit: 3, 5
zlim: ~
## frame rate: 100
fps: ~
## scatter plot: false
scatter: ~
## show text value: false
show_value: ~
```
### Useful modules
- `matsense.uclient`
- `Uclient`: interface to receive data from server
- `matsense.process`: data processing tools
- `DataHandlerPressure`: process pressure data (conversion & filtering & calibration)
- `BlobParser`
- `Interpolator`
- `PointSmoother`
- `CursorController`
- `PressureSelector`
- `matsense.datasetter`: data setter, using serial port or file data
- `DataSetterSerial`
- `DataSetterFile`
- `matense.tools`: configuration and other helpful tools
- `matsense.filemanager`: file I/O tools
- `matsense.visual`: visualization tools
- `from matsense.visual.player_matplot import Player3DMatplot`: 3D player using Matplotlib
- `from matsense.visual.player_pyqtgraph import Player3DPyqtgraph`: 3D player using PyQtGraph
## Server-Client Protocol
Use `matclient -i` to control server.
The underlying server-client communication protocol is：
| Name | meaning | Value | Format | Return | Return format |
| ------------ | ------------------------------------- | ------------------ | ------------ | -------------------- | -------------- |
| CLOSE | close server | 0 | 1byte | status | 1byte |
| DATA | get a data frame | 1 | 1byte | frame+index | 256double+1int |
| RAW | get a raw data frame | 2 | 1byte | frame+index | 256double+1int |
| REC_DATA | ask server to record data to file | 3(+filename) | 1byte+string | status+filename | 1byte+string |
| REC_RAW | ask server to record raw data to file | 4(+filename) | 1byte+string | status+filename | 1byte+string |
| REC_STOP | ask server to stop recording | 5 | 1byte | status | 1byte |
| RESTART | restart server with config string | 6(+config_str) | 1byte+string | status+config_string | 1byte+string |
| RESTART_FILE | restart server with config filename | 10+config_filename | 1byte+string | status+config_string | 1byte+string |
| CONFIG | get server config | 7 | 1byte | status+config_string | 1byte+string |
| DATA_IMU | get IMU data | 9 | 1byte | IMU_frame+index | 6double+1int |
- `status` (1 byte): 0 for success and 255 for failure
## Author
Atomie CHEN: atomic_cwh@163.com
Raw data
{
"_id": null,
"home_page": "https://github.com/atomiechen/MatSense",
"name": "MatSense",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": "matrix sensor, signal processing, 3D visualization",
"author": "Atomie CHEN",
"author_email": "atomic_cwh@163.com",
"download_url": "https://files.pythonhosted.org/packages/36/5d/adf25a1b4abea9c524981965a12e7d2d5ff68546a87434cb155ae9c49ea0/matsense-0.4.1.tar.gz",
"platform": null,
"description": "# MatSense\n\n[](https://pypi.org/project/MatSense/)\n\nA toolkit that supports both real-time and off-line matrix sensor data processing and 3D visualization. \n\n\n\nA typical real-time data flow would be in a client-server manner:\n\n- Matrix sensor data: collected (e.g. by Arduino) and transmitted via a serial port to the computer.\n- Data processing: the series of matrix data frames are processed and served by the server.\n- Applications: clients connect to server to get processed data and do further work.\n\nData can also be recorded to and processed from files. \n\n<img src=\"https://raw.githubusercontent.com/atomiechen/MatSense/main/img/player.png\" alt=\"schematic\" width=\"450\" />\n\n3D visualization tools are provided to play real-time stream or recorded data.\n\n\n\n\n## Installation\n\nFrom PyPI:\n\n```sh\npip install MatSense\n```\n\nThis will install [Matplotlib](https://matplotlib.org/) to implement 3D visualization tools. \n\nIf you want to further try [PyQtGraph](https://www.pyqtgraph.org/) as visualization method:\n\n```sh\npip install MatSense[pyqtgraph]\n```\n\n\n\n## Usage\n\n### Off-the-shelf tools\n\n3 handy tools are provided. Pass `-h` to get detailed information.\n\n- `matserver` / `python -m matsense.server`\n - functions:\n - receive data from serial port, process and serve\n - process data from file(s) and output to file\n - other helpful functions\n - supported processing methods:\n - voltage-pressure conversion (optional for pressure data)\n - spatial filter (in-frame denoising): none, ideal, butterworth, gaussian\n - temporal filter (pixel-wise between-frame denoising): none, moving average, rectangular window\n - calibration: static or dynamic\n- `matclient` / `python -m matsense.client`: receive server data, process and visualize; or control server via interactive commands\n - supported processing methods:\n - interpolation\n - blob parsing\n- `matdata` / `python -m matsense.data`: visualize file data, or process off-line data\n\n### Configuration\n\nAll 3 tools can be totally configured by a YAML configuration file:\n\n```sh\n## server console\nmatserver --config your_config.yaml\n\n## client console\nmatclient --config your_config.yaml\n\n## off-line data processing\nmatdata --config your_config.yaml\n```\n\nPriority: commandline arguments > config file > program defaults.\n\nA template YAML configuration (unused options can be set to `~` or removed):\n\n```yaml\n## template configurations\n## ~ for defaults\n\n## configurations for matserver mode\nserver_mode:\n ## enable backend service\n service: ~\n ## enable visualization or not (suppress service)\n visualize: ~\n ## enumerate all serial ports\n enumerate: ~\n\n ## (suppress serial) simulated data source without actual serial connection\n ## debug mode: true, false\n debug: ~\n\n ## (suppress serial) use file as data source or not: true, false\n use_file: ~\n\n## configurations for matclient mode\nclient_mode:\n ## make client present raw data\n raw: ~\n ## interactive command line mode\n interactive: ~\n\n## configurations for matdata mode\ndata_mode:\n ## process file data instead of visualization\n process: ~\n\n## configurations for file data\ndata:\n ## input filename(s), filename or a list of filenames: [a.csv, b.csv, ...]\n in_filenames: ~\n ## output filename, default filename is used when not provided\n out_filename: ~\n\n## configurations for matrix sensor\nsensor:\n ## sensor shape: [16, 16], [8, 8], [6, 24]\n shape: ~\n ## total points, can be set to ~\n total: ~\n ## 0/1 mask to exclude non-existent points\n ## |- for multiline without a newline in the end\n mask: ~\n\n## configurations for serial port\nserial:\n ## baudrate: 9600, 250000, 500000, 1000000\n baudrate: ~\n ## serial port timeout, in seconds\n timeout: ~\n ## serial port\n port: ~\n ## data transmission protocol: simple, secure\n protocol: ~\n ## support IMU data\n imu: ~\n\n## configurations for client-server connections\nconnection:\n ## use UDP or UNIX domain socket\n udp: ~\n ## udp address format: 127.0.0.1:20503\n ## UNIX deomain socket address format: /var/tmp/unix.socket.server\n server_address: ~\n client_address: ~\n\n## configurations for data processing\nprocess:\n ### voltage to the reciprocal of resistance\n ## reference voltage: 255, 255/3.6*3.3\n V0: ~\n ## constant factor: 1\n R0_RECI: ~\n ## convert voltage to resistance: true\n convert: ~\n\n ### server data processing\n ## no filtering and calibration\n raw: ~\n ## time of warming up in seconds: 1\n warm_up: ~\n ## spatial filter: none, ideal, butterworth, gaussian\n filter_spatial: ~\n ## spatial filter cut-off freq: 3.5\n filter_spatial_cutoff: ~\n ## Butterworth filter order: 2\n butterworth_order: ~\n ## temporal filter: none, moving average, rectangular window\n filter_temporal: ~\n ## temporal filter size: 15\n filter_temporal_size: ~\n ## rectangular window filter cut-off frequency: 0.04\n rw_cutoff: ~\n ## calibrative frames, 0 for no calibration: 0, 200\n cali_frames: ~\n ## calibration frame window size, 0 for static and >0 for dynamic: 0, 10000\n cali_win_size: ~\n ## intermediate result: 0, 1, 2\n ## 0: convert voltage to reciprocal resistance\n ## 1: convert & spatial filter\n ## 2: convert & spatial filter & temporal filter\n intermediate: ~\n\n ### (optional) client data processing\n ## interpolation shape, default to sensor.shape\n interp: ~\n ## interpolation order: 3\n interp_order: ~\n ## filter out blobs: true\n blob: ~\n ## total blob number: 3\n blob_num: ~\n ## blob filter threshole: 0.1, 0.15\n threshold: ~\n ## special check for certain hardwares: false\n special_check: ~\n\npointing:\n ## value bound for checking cursor moving state: 0\n bound: ~\n ## directly map coordinates or relatively (suppress trackpoint)\n direct_map: ~\n ## use ThinkPad's TrackPoint (red dot) control style\n trackpoint: ~\n ## smoothing\n alpha: ~\n\n## configurations for visualization\nvisual:\n ## using pyqtgraph or matplotlib\n pyqtgraph: ~\n ## z-axis limit: 3, 5\n zlim: ~\n ## frame rate: 100\n fps: ~\n ## scatter plot: false\n scatter: ~\n ## show text value: false\n show_value: ~\n```\n\n### Useful modules\n\n- `matsense.uclient`\n - `Uclient`: interface to receive data from server\n- `matsense.process`: data processing tools\n - `DataHandlerPressure`: process pressure data (conversion & filtering & calibration)\n - `BlobParser`\n - `Interpolator`\n - `PointSmoother`\n - `CursorController`\n - `PressureSelector`\n- `matsense.datasetter`: data setter, using serial port or file data\n - `DataSetterSerial`\n - `DataSetterFile`\n\n- `matense.tools`: configuration and other helpful tools\n- `matsense.filemanager`: file I/O tools\n- `matsense.visual`: visualization tools\n - `from matsense.visual.player_matplot import Player3DMatplot`: 3D player using Matplotlib\n - `from matsense.visual.player_pyqtgraph import Player3DPyqtgraph`: 3D player using PyQtGraph\n\n\n\n\n## Server-Client Protocol\n\nUse `matclient -i` to control server. \n\nThe underlying server-client communication protocol is\uff1a\n\n| Name | meaning | Value | Format | Return | Return format |\n| ------------ | ------------------------------------- | ------------------ | ------------ | -------------------- | -------------- |\n| CLOSE | close server | 0 | 1byte | status | 1byte |\n| DATA | get a data frame | 1 | 1byte | frame+index | 256double+1int |\n| RAW | get a raw data frame | 2 | 1byte | frame+index | 256double+1int |\n| REC_DATA | ask server to record data to file | 3(+filename) | 1byte+string | status+filename | 1byte+string |\n| REC_RAW | ask server to record raw data to file | 4(+filename) | 1byte+string | status+filename | 1byte+string |\n| REC_STOP | ask server to stop recording | 5 | 1byte | status | 1byte |\n| RESTART | restart server with config string | 6(+config_str) | 1byte+string | status+config_string | 1byte+string |\n| RESTART_FILE | restart server with config filename | 10+config_filename | 1byte+string | status+config_string | 1byte+string |\n| CONFIG | get server config | 7 | 1byte | status+config_string | 1byte+string |\n| DATA_IMU | get IMU data | 9 | 1byte | IMU_frame+index | 6double+1int |\n\n- `status` (1 byte): 0 for success and 255 for failure\n\n\n\n## Author\n\nAtomie CHEN: atomic_cwh@163.com\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A toolkit for matrix sensor data processing \u9635\u5217\u4f20\u611f\u5668\u6570\u636e\u5904\u7406\u5de5\u5177\u5e93",
"version": "0.4.1",
"project_urls": {
"Bug Tracker": "https://github.com/atomiechen/MatSense/issues",
"Homepage": "https://github.com/atomiechen/MatSense",
"Source Code": "https://github.com/atomiechen/MatSense"
},
"split_keywords": [
"matrix sensor",
" signal processing",
" 3d visualization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "17b259b2358e5d2f7be0c6630ac8c8c1aabbfcfc08a02ccd5bdc0054b5252dd5",
"md5": "ab0ac419ab8e9cd5a62b4ca2c58a662a",
"sha256": "6bc4396c884f8a94896e3697c493608e97ec8109f1b3365ee7638fc6fd31b3fe"
},
"downloads": -1,
"filename": "MatSense-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab0ac419ab8e9cd5a62b4ca2c58a662a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 52562,
"upload_time": "2024-05-27T13:36:56",
"upload_time_iso_8601": "2024-05-27T13:36:56.544023Z",
"url": "https://files.pythonhosted.org/packages/17/b2/59b2358e5d2f7be0c6630ac8c8c1aabbfcfc08a02ccd5bdc0054b5252dd5/MatSense-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "365dadf25a1b4abea9c524981965a12e7d2d5ff68546a87434cb155ae9c49ea0",
"md5": "b43b0f8829473f17b968f3641d91f6c3",
"sha256": "f91efc8b1efe4d3f3ea7acd7ad21a52fdadf60f2127ffa474404344a4bd5fc99"
},
"downloads": -1,
"filename": "matsense-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "b43b0f8829473f17b968f3641d91f6c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 43513,
"upload_time": "2024-05-27T13:37:01",
"upload_time_iso_8601": "2024-05-27T13:37:01.920692Z",
"url": "https://files.pythonhosted.org/packages/36/5d/adf25a1b4abea9c524981965a12e7d2d5ff68546a87434cb155ae9c49ea0/matsense-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-27 13:37:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "atomiechen",
"github_project": "MatSense",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "matsense"
}
JSON
