Library under development, everything here is subject to change.
Mediocre, or Mediocre Extraction of Data Involving an Optical Character Recognition Engine, is a configurable application for extracting and emitting data in real-time from videos.
Key libraries used:
- gRPC for exposing functions in a language and platform neutral manner
- OpenCV for various image processing methods
- Tesseract for optical character recognition
Currently, the best way to run mediocre is via the pre-built docker images, though there are plans to provide executables for various platforms in the future.
Docker hub: https://hub.docker.com/repository/docker/obroomhall/mediocre
Tag convention:
obroomhall/mediocre:master
is the most up-to-date imageobroomhall/mediocre:pr-x
is built from each pull request, wherex
is the pull request numberobroomhall/mediocre:sha-abc
is built from each commit, whereabc
is the commit hashobroomhall/mediocre:*-cache
exist to speed up subsequent builds, these are not runnable- There will also be some
vX.Y.Z
tags after the first release
You should expose port 8081
for the gRPC server, for example:
docker run -p 8081:8081 --name mediocre obroomhall/mediocre:master
If you want to connect securely, you must provide valid TLS certificates.
docker run -p 8081:8081 --name mediocre obroomhall/mediocre:master -v /path/to/your/certs:/certificates:ro
One way to invoke the functions in mediocre is to use a gRPC tool, some of which are listed in the grpc-ecosystem project. Ideally choose a tool that uses gRPC server reflection, so that it can automatically detect which methods mediocre exports.
Some that I have used in the past:
- grpc-client-cli - an interactive gRPC client command line tool
- grpcui - an interactive web UI for gRPC
You can also use invoke mediocre from any language that has gRPC support, for example; C/C++, C#, Go, Java, Python. The full list of officially supported languages can be found in the gRPC docs.
For some languages, you can add a dependency to mediocre via a Buf.Build Remote Package, this is the easiest method, but is limited to the languages currently supported by the Buf Schema Registry.
If there is no remote package available for your language, you must build the protobuf source files yourself. Instructions on how to do that can be found at https://buf.build/plugins.
For example, to build source files for C#, you could create a buf.gen.yaml
as:
version: v1
managed:
enabled: true
plugins:
- plugin: buf.build/grpc/csharp:v1.56.0
out: gen
- plugin: buf.build/protocolbuffers/csharp
out: gen
And then build with buf generate
.
Documentation can be found on the Buf Schema Registry.
Mediocre was developed in JetBrains CLion, and though other IDEs can be used the instructions below are tailored towards building and running in CLion.
- Run the
Docker Toolchain with Cache
script run configuration to build the latest image asmediocre:local-develop
- This uses registry cache to speed up the initial build (should finish building in a matter of seconds)
- Use this script if there have been any significant changes to the docker image (full rebuilds take about an hour)
- Go to
File > Settings > Build, Execution, Deployment
and add aDocker
toolchain- For image use the previously built
mediocre:local-develop
image - For container settings, expose the port mediocre listens on
-p 0.0.0.0:8081:8081 --rm
- For CMake use
cmake
- For debugger, use
\local\gdb\install\bin\gdb
- For image use the previously built
- Build the protobuf files using the
proto-objects
cmake run configuration
For library source file changes, run the mediocre
cmake run configuration.
Otherwise, for docker changes, run the Build and Run
docker run configuration.
You can run the proxy alongside by downloading the latest release,
adding it to your PATH, and then running the Proxy
run configuration. You can run the proxy with or without TLS certificates.
If you do not have your own TLS certificates, you can generate your own self-signed certificates. You can follow the Let's Encrypt guide for making and trusting your own certificates. The general steps are:
- Install minica
- Generate root and end certificates
minica --domains localhost
- Import the root certificate
Import-Certificate -FilePath .\minica.pem -CertStoreLocation cert:\CurrentUser\Root
- Mount the end certificates to your docker container
-v /path/to/your/certs/localhost:/certificates:ro
If you are making changes in this project and a dependent project, such as mediocre-configure, you will likely want to use your locally updated protobuf definitions in the dependent project, before committing changes.
Other languages may vary, but to compile for typescript:
- In
./@buf/typescript
runnpm install && npm link
- In the external project run
npm link @buf/broomy_mediocre.community_timostamm-protobuf-ts
- Each time a protobuf definition changes, run
buf generate
in the project root directory