Python-based functions to build and parse message strings according to the ANSI MH-10 standard and generate a Data-Matrix-Code from it wrapped in a mirco-service for a convenient web-frontend.
(Other standards may be implemented later.)
There are three options:
- vanilla package/code: The python package DataMatrixCode includes the code to build, parse, generate DMCs (using the treepeom package)
- api: A fastAPI-based web-service that wraps the DataMatrixCode package to a minimal web-api
- app (with convenient GUI front-end): This web-service is build on streamlit, which is a python-package for building an interactive website and includes also a web server engine.
The project is meant to be compiled to its Docker containers. See Dockerfile for installation instructions.
Install Python 3.9 (or later) and its package management PIP. Create a virtual environment; then install the requirements to it
pip install -r api.requirements.txt
pip install -r app.requirements.txt
Now run fastAPI and / or streamlit:
uvicorn api-main:api
streamlit run app-main.pyYou can access the services now in your webbrowser on the default ports: http://localhost:8000 and http://localhost:8501 for the api and the app respectively
Build docker container based on Python3.9
docker build --tag=dmc-generator-api -f api.Dockerfile .
docker build --tag=dmc-generator-app -f app.Dockerfile .Run containers
docker run -d -p 5001:8000 --name=fastapi-dmc-generator dmc-generator-api
docker run -d -p 5002:8501 --name=streamlit-dmc-generator dmc-generator-appWhere you can now access the services on: http://localhost:5001 and http://localhost:5002.
One can set all options also as environment variables with the prefix DMC_ ,e.g.:
docker run -d -p 5002:8501 --name=streamlit-dmc-generator -e DMC_TITLE="My Data-Matrix-Generator" -e DMC_NUMBER_OF_QUIET_ZONE_MODULES=10 dmc-generator-app(Options are the same as in the config.toml-file but with the prefix DMC_ and an underscore _ before capital letters as all environment variables should be capital letters only, e.g. NumberOfQuietZoneModules in config.toml => DMC_NUMBER_QUIET_ZONE_MODULES as enviroment variable.)
You may also want to adjust the text on the top of the page with the keywords Title, Header, Subheader, and Text (in descending font) in the config.toml-file or DMC_TITLE, DMC_HEADER, DMC_SUBHEADER, and DMC_TEXT respectively as environment vairalbes.
streamlit-based web-app
The initial page shows only the required fields, if any are specified. If not, the initial page consists of a single row (data identifier as drop down menu + input field).
Note that you can change the options dynamically when expanding the container "options". The options are stored for the session. The default options can be specified for in the configuration file when starting the streamlit server (for examples see below.)
When selecting a new data identifier, the corresponding explanation is displayed above the row:
and a warning is issued when the input does not comply with the expected format.
For generating a code simply click the button "generate". A correct message string is created automatically and the number of ASCII characters of this string is displayed next to the image of the code.
Note that no DMC is generated if one leaves one of the required fields empty.
streamlit can be configured via a TOML file config.toml, e.g. the primarycolor of the overall theme (see config file as example or the streamlit-docs).
We extended this file to add a section [DMC], where one can specify field identifiers that should be required in the code. This is an array of strings. One can connect two identifiers as OR with an | symbol. See example.
[DMC]
requiredDataIdentifiers = ["P", "S|T", "V"]You can specify the default option values with the following keys (this are the default values, which do not have to be explicitly specified.)
[DMC]
UseMessageEnvelope = true
UseFormatEnvelope = true
RectangularDMC = false
NumberOfQuietZoneModuls = 2
ExplainDataIdentifiers = trueWith regard to docker containers, one can set all configurations via environment variables. Streamlit uses upper snake case wirtings with the prefix STREAMLIT_, e.g. the keyword primaryColor in the [browser] section becomes STREAMLIT_BRWOSER_PRIMARY_COLOR=#2D4275.
To configure the data matrix code, we follow this pattern using the prefix DMC_ (and no sections.) I.e. use DMC_NUMBEROF_QUIET_ZONE_MODULS=2 to specify the key NumberOfQuietZoneModuls.
Find an exemplary docker-compose.yaml in this repo.
fastapi-based web-api
fastapi conveniently builds an automatic documentation at the /docs endpoint. Please check these examples there.
max-scw
This project is licensed under the AGLPv3 - see the LICENSE file for details.
The python library treepeom, which is used to generate DMCs, uses ghostscript. The open-source license of ghostscript uses a AGLPv3 license (strong copy-left license, i.e. all code in a project that uses ghostscript must be made available as open-source with the same license) but also offers a commercial license. Therefore the project is also bined to AGLPv3 license. If there is a way to replace ghostscript, I would be happy to publish the code under a more liberal scheme.
| Version | Description |
|---|---|
| 0.1.0 | initial release |
| 0.1.1 | bugfix initial release |
| 0.2.0 | streamlit config via environment variables |
| 0.2.1 | fix missing datetime handling |
| 0.2.2 | DMC + streamlit config via environment variables (bugfix) |
maintenance + minor feature development