OCR Server - dokumentacja

Rozdział 1. Instalacja

1.1. Wymagania wstępne

Program jest z założenia kompatybilny z systemami Linux na architekturze x86. Powinien działać bez problemów na wszystkich współczesnych dystrybucjach GNU/Linux.

Proszę sprawdzić czy narzędzia tcpserver i tcpclient są zainstalowane w jednej z lokalizacji uwzględnionych w zmiennej środowiskowej PATH. Narzędzia te pochodzą z pakietu ucspi-tcp.

Proszę sprawdzić czy narzędzie curl jest zainstalowane w jednej z lokalizacji uwzględnionych w zmiennej środowiskowej PATH. Curl jest potrzebny przy procesie aktywacji.

Powyższe zalecenia należy wziąć pod uwagę zgłaszając problemy związane z aplikacją.

1.2. Instalacja programu

Aby zainstalować OCR serwer należy po prostu rozpakować plik archiwum "ocr_server-(numer wersji).tar.bz2" do docelowej lokalizacji.

Nie ma potrzeby wykonywania dodatkowych zadań.

1.3. Aktywacja

OCR Server nie będzie funkcjonował bez aktywacji.

Należy być zalogowanym jako root aby aktywować aplikację. Proszę uruchomić skrypt activate.sh. OCR Server jest aktywowany za pośrednictwem Internetu. Połączenie z Internetem jest wymagane. Aktywacja jest przeprowadzana automatycznie. Proszę wpisać numer seryjny w odpowiednim momencie.

Rozdział 2. Uruchomienie

2.1. Uruchomienie serwera

Aby uruchomić serwer, należy wywołać skrypt ocr_server.sh. OCR Server uruchomi się na domyślnym porcie numer 10000. Jeśli wymagane jest użycie innego portu należy dodać argument linii poleceń jak poniżej:

./ocr_server.sh 10001

2.2. Uruchomienie klienta

Aby uruchomić klienta, należy wywołać skrypt ocr_client.sh. Dwa argumenty linii poleceń są wymagane. Pierwszy argument to adres IP komputera na którym jest uruchomiony OCR Server. Jeśli numer portu nie jest uwzględniony to klient spróbuje połączyć się używając domyślnego numeru portu 10000. Drugi argument to ścieżka do pliku wejściowego. Proszę zapoznać się z przykładami poniżej:

./ocr_client.sh 127.0.0.1 ~/images/test.jpg

./ocr_client.sh 192.168.0.2:10001 fax_for_ocr.pdf

Jeśli ocr_client.sh zostanie uruchomiony z nieprawidłowymi argumentami linii poleceń, zostanie wyświetlony poniższy tekst pomocy:

Usage: ocr_client.sh HOST[:PORT] [OPTION ...] FILE
HOST            OCR Server host, eg. 127.0.0.1
PORT            OCR Server port, default is 10000
-e FORMAT       export format: text | rtf | pdf | html | bmp | jpeg | png | tiff_jpeg | tiff_zip
-m LANG_CODE    messages language, eg. de or fr
-r LANG_CODE    recognition language, eg. de or fr
-w WIDTH        image width (for image format export)
-h HEIGHT       image height (for image format export)

Rozdział 3. Protokół

3.1. Ogólny opis

OCR Server i klient porozumiewają się używając protokołu TCP/IP. W większości przypadków bardziej praktyczne będzie bezpośrednie użycie tego protokołu we własnej aplikacji zamiast uruchamiania narzędzia klienckiego.

Komendy i odpowiedzi serwera są proste, samoopisujące się oraz czytelne dla człowieka.

3.2. Get server version

Gdy ta komenda zostanie wysłana OCR Server poda swoją wersję.

3.3. End session

Gdy ta komenda zostanie wysłana OCR Server zakończy bieżącą sesję i przerwie połączenie.

3.4. Set protocol version to

Gdy ta komenda zostanie wysłana OCR Server zmieni bieżący protokół na podaną wersję jeśli jest ona obsługiwana.

W chwili obecnej tylko wersja 1 protokołu jest obsługiwana.

3.5. Set messages language to

Gdy ta komenda zostanie wysłana OCR Server zmieni bieżący język komunikatów na podany jeśli jest on obsługiwany.

Język komunikatów to język używany do wysyłania błędów oraz podpowiedzi dotyczących rozpoznawania.

3.6. Set recognition language to

Gdy ta komenda zostanie wysłana OCR Server zmieni bieżący język rozpoznawania na podany jeśli jest on obsługiwany.

Język rozpoznawania to język używany do rozpoznawania tekstu w dokumentach. Ustawienie poprawnego języka rozpoznawania, odpowiadającego dokumentom, które będą przetwarzane podczas procesu OCR jest bardzo istotne ponieważ OCR Server używa słowników wyrazów aby zwiększyć jakość rozpoznawania.

3.7. Upload document

Gdy ta komenda zostanie wysłana OCR Server odbierze plik dokumentu źródłowego, sprawdzi jego format oraz przetworzy go, aby uzyskać obrazy wszystkich stron dokumentu.

3.8. Get number of pages

Gdy ta komenda zostanie wysłana OCR Server poda ilość stron, które zostały pozyskane z odebranego pliku dokumentu.

3.9. Set image width to

Gdy ta komenda zostanie wysłana OCR Server zmieni szerokość obrazu zwracanego przez komendę "Get image of page".

3.10. Set image height to

Gdy ta komenda zostanie wysłana OCR Server zmieni wysokość obrazu zwracanego przez komendę "Get image of page".

3.11. Set image format to

Gdy ta komenda zostanie wysłana OCR Server zmieni format obrazu zwracanego przez komendę "Get image of page".

Obsługiwane są następujące formaty obrazów:

3.11.1. bmp

Format pliku BMP, nazywany czasem bitmapą, jest formatem obrazu używanym do przechowywania cyfrowych obrazów, szczególnie w środowiskach systemów operacyjnych MS Windows i OS/2.

3.11.2. jpeg

JPEG File Interchange Format (JFIF) jest formatem obrazu służącym wymianie plików JPEG zgodnych ze standardem JPEG Interchange Format (JIF).

3.11.3. png

Portable Network Graphics (PNG) jest formatem obrazu używającym bezstratną kompresję danych. PNG został stworzony aby udoskonalić i zastąpić format GIF, jako format obrazu nie wymagający licencji patentowej.

3.11.4. tiff_jpeg

Tagged Image File Format (w skrócie TIFF) jest formatem plików służącym przechowywaniu obrazów, włącznie z fotografiami oraz szkicami. Ten format używa kompresji JPEG.

3.11.5. tiff_zip

Tagged Image File Format (w skrócie TIFF) jest formatem plików służącym przechowywaniu obrazów, włącznie z fotografiami oraz szkicami. Ten format używa kompresji ZIP.

3.12. Get image of page

Gdy ta komenda zostanie wysłana OCR Server wyśle obraz strony o podanym numerze.

Domyślna szerokość i wysokość zwracanego obrazu jest odczytywana z dokumentu źródłowego, ale mogą być one zmienione przy użyciu komend "Set image width to" i "Set image height to".

Domyślnym formatem zwracanego obrazu jest PNG ale może być on zmieniony przy użyciu komendy "Set image format to".

3.13. Recognize page

Gdy ta komenda zostanie wysłana OCR Server przeprowadzi proces rozpoznawania strony o podanym numerze.

3.14. Export document as

Gdy ta komenda zostanie wysłana OCR Server wyśle rezultaty rozpoznawania w podanym formacie.

Obsługiwane są poniższe formaty eksportu:

3.14.1. plain text

Format tekstu niesformatowanego (Plain text) jest idealnym rozwiązaniem dla indeksowania oraz przeszukiwania. Może być edytowany przy użyciu edytorów tekstu.

3.14.2. rtf

Rich text format jest idealnym rozwiązaniem dla potrzeb dalszej edycji. Zachowuje on układ dokumentu oraz osadzone obrazy. Może być edytowany przy użyciu większości nowoczesnych procesorów tekstu.

3.14.3. pdf

Przenośny format dokumentu (Portable document format) jest idealnym rozwiązaniem dla drukowania. Edycja jest w chwili obecnej ograniczona do pewnych wyspecjalizowanych, komercjalnych aplikacji.

3.14.4. html

Format HTML jest idealnym rozwiązaniem dla publikowania rozpoznanego tekstu na stronach internetowych. Może być edytowany przy użyciu edytorów tekstu oraz narzędzi webmasterskich.

3.15. Pobieranie informacji o aktualnej licencji

Każda licencja ma ograniczenie na ilość jednostek pomiaru (stron lub znaków) przetwarzanych podczas okresu czasu (godziny, dnia, tygodnia, miesiąca lub roku). Dodatkowo istnieją licencje, które mają limit nieodnawialny.

Licencje mogą być tymczasowe (wygasną w konkretnym dniu lub po określonej liczbie dni) lub stałe.

3.15.1. Get serial number

Gdy ta komenda zostanie wysłana OCR Server poda numer seryjny aktualnej licencji.

3.15.2. Get counter measure unit

Gdy ta komenda zostanie wysłana OCR Server poda jednostkę pomiaru ograniczenia aktualnej licencji. Może to być "pages" (strony) lub "characters" (znaki).

3.15.3. Get limitation period

Gdy ta komenda zostanie wysłana OCR Server poda okres czasu ograniczenia aktualnej licencji. Może to być "hour" (godzina), "day" (dzień), "week" (tydzień), "month" (miesiąc), "year" (rok) or "infinite" (nieograniczony). Jeśli jest to "infinite" to licencja ma limit nieodnawialny.

3.15.4. Get units per period

Gdy ta komenda zostanie wysłana OCR Server poda maksymalną ilość jednostek, które mogą być wykorzystane w jednym okresie czasu według ograniczenia aktualnej licencji.

3.15.5. Get remaining units

Gdy ta komenda zostanie wysłana OCR Server poda pozostałą ilość jednostek, które mogą mogą być wykorzystane w bieżacym okresie czasu według ograniczenia aktualnej licencji.

3.15.6. Get expiration date

Gdy ta komenda zostanie wysłana OCR Server poda datę wygaśnięcia aktualnej licencji. Zwracana jest data w formacie ISO (YYYY-MM-DD) lub "none" (brak) jeśli licencja jest stała.

3.16. Transmisja plików

Niektóre polecenia jak "Upload document" lub "Export document as" wymagają przesłania pliku do lub z OCR Server. Protokół zawiera możliwość transmisji pliku i sprawdzenia jego poprawności.

3.16.1. Nagłówek pliku

Każdy przesyłany plik rozpoczyna się nagłówkiem. Każdy nagłówek składa się z trzech linii. Każda linia rozpoczyna się prefiksem. Prefiks jest oddzielony od wartości dwukropkiem i spacją.

Poniżej znajduje się przykładowy nagłówek pliku:

Extension: jpg
Size: 10244
Checksum: 14514

3.16.2. Dane pliku

Dane pliku następują bezpośrednio za nagłówkiem. Są prostym strumieniem bajtów i nie są zakodowane.

3.16.3. Wyliczanie sumy kontrolnej

Suma kontrolna pliku jest wyliczana z użyciem rozszerzonego algorytmu XOR. Ma zawsze długość 16 bitów. Pierwsze 8 bitów reprezentuje wszystkie bajty pliku zXORowane razem. Drugie 8 bitów reprezentuje wszystkie zanegowane bajty pliku zXORowane razem. Negowanie jest konieczne do wykrycia zagubienia bajtów o wartości 0.

Poniżej znajduje się przykładowa funkcja wyliczająca sumę kontrolną (język C):

int calculate_checksum(const char* data, int size)
{
	char checksum_1 = 0;
	char checksum_2 = 0;
	for (int i = 0; i < size; i++)
	{
	checksum_1 ^= data[i];
	checksum_2 ^= (~data[i]);
	}
	return ((unsigned char)checksum_1 << 8) + (unsigned char)checksum_2;
}