/uic-918-3

Package for decoding and parsing barcodes according to UIC-918.3 specification, which are used commonly on public transport online tickets.

Primary LanguageTypeScriptMIT LicenseMIT

uic-918-3.js

TypeScript Build Status Coverage Status Maintainability npm version code style: prettier

A Node.js package written in Typescript for decoding and parsing barcodes according to the "UIC 918.3" specification, which is commonly used on Print and Mobile Tickets from public transport companies (e.g. Deutsche Bahn).

Installation

To install the latest released version:

npm install uic-918-3

Or checkout the master branch on GitHub:

git clone https://github.com/justusjonas74/uic-918-3.git
cd uic-918-3
npm install

Usage

import { readBarcode } from 'uic-918-3';

// Input could be a string with path to image...
const image = '/path/to/your/file.png';
// ... or a Buffer object with an image
const image_as_buffer = fs.readFileSync('/path/to/your/file.png');

readBarcode('foo.png')
  .then((ticket) => console.log(ticket))
  .catch((error) => console.error(error));

Options

Following options are available:

import { readBarcode } from 'uic-918-3';

const image = '/path/to/your/file.png';
const options = {
  verifySignature: true // Verify the signature included in the ticket barcode with a public key set from a Public Key Infrastructure (PKI). The PKI url is set inside './lib/cert_url.json'. Default is 'false'.
};

uic.readBarcode(image, options).then((ticket) => {
  console.log(ticket.validityOfSignature); // Returns "VALID", "INVALID" or "Public Key not found"
  // ticket.isSignatureValid is deprecated. Use validityOfSignature instead.
});
//

Returning object

The returning object consists of (among other things) one or more TicketDataContainers which hold ticket data for different purposes. The most interesting containers are:

  • **U_HEAD** The ticket header ...
  • **U_TLAY** A representation of the informations which are printed on the ticket.
  • **0080BL** A specific container on tickets from Deutsche Bahn. Consists of all relevant information which will be used for proof-of-payment checks on the train.
  • **0080VU** A specific container on (some) tickets from Deutsche Bahn. This container is used on products, which are also accepted by other carriers, especially (local) public transport companies. Get more information about this container here.

Optimize your files

Actually the barcode reader is very dump, so the ticket you want to read, should be optimised before using this package. A better reading logic will be added in future versions.

Images

Actually the package only supports images with a "nice to read" barcode. So it's best to crop the image to the dimensions of the barcode and save it as a monochrome image (1 bit colour depth).

Extract barcode images from PDF files

You have to extract the barcode image from your PDF. The fastest (but not the best) way is to make a screen shot and save it as described before. If you're using Linux or Mac OS X a much better way is to use poppler-utils and imagemagick:

# Extract images from pdf to .ppm or .pbm images. The last argument is a prefix for the extracted image file names.
pdfimages your-ticket.pdf your-ticket
# convert .ppm/.pbm to a readable format (png)
convert your-ticket-00x.ppm your-ticket-00x.png;

Expected Quality

The UIC 913.3 specifications aren't available for free, so the whole underlying logic is build upon third party sources, particularly the Python script onlineticket from Hagen Fritzsch, the diploma thesis from Roman Waitz and the Wikipedia discussion about Online-Tickets. Therefore results from this package (especially the parsing logic) should be taken with care. Please feel free to open an issue, if you guess there's a wrong interpretation of data fields or corresponding values.

Contributing

Feel free to contribute.