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.

Do wykonania upgradu niezbędne jest narzędzie xdelta3. Proszę sprawdzić czy narzędzie to jest zainstalowane w jednej z lokalizacji uwzględnionych w zmiennej środowiskowej PATH. Narzędzie to pochodzi z pakietu xdelta w wersji 3 lub z pakietu xdelta3.

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.

Do instalacji programu w wersji "upgrade" niezbędny jest plik archiwum z ostatnią dostępną pełną wersją instalacyjną poprzedzającą instalowaną wersję. W docelowej lokalizacji należy wykonać następujące polecenie:

XDELTA="-R -c -s ocr_server-(numer wersji pełnej).tar.bz2" \
	tar --use-compress-program=xdelta3 -xvf ocr_server-(numer wersji upgrade).tar.xdelta3

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

Często zachodzi potrzeba uruchomienia serwera w tle, aby pozostał on aktywny po wylogowaniu się użytkownika. Efekt taki można uzyskać posługując się przedstawioną poniżej komendą. Wszelkie komunikaty wypisywane dotychczas na konsoli zapisywane będą do pliku "ocr_server.log".

nohup ./ocr_server.sh > ocr_server.log 2>&1 &

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. Obsługiwane języki

3.1. Języki obsługiwane podczas rozpoznawania tekstu

Tabela 3-1. Języki obsługiwane podczas rozpoznawania tekstu i odpowiadające im kody

Silnik programu OCR Server potrafi obsługiwać także inne, nie wymienione w tabeli języki podczas rozpoznawania tekstu. Nie mają one jednak odpowiadających im kodów. W sprawie obsługi innych języków prosimy o kontakt z producentem lub dystrybutorem.

3.2. Dostępne języki komunikatów serwera

Tabela 3-2. Dostępne języki komunikatów serwera i odpowiadające im kody

Rozdział 4. Protokół

4.1. Zasady ogólne

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.

Poza nielicznymi wyjątkami wymiana informacji pomiędzy klientem i serwerem następuje w formie tekstowej. Komendy i odpowiedzi serwera są proste, samoopisujące się oraz czytelne dla człowieka. Każdy komunikat stanowi jedną linię tekstu i zakończony jest znakiem nowego wiersza o kodzie 0x0A ('\n').

Na początku dialogu oraz po zakończeniu wykonywania każdej z komend serwer wysyła wiadomość "Send a command now." oznaczającą gotowość do wykonywania poleceń i będącą zaproszeniem do wysłania kolejnej komendy. Komunikat ten wysyłany jest niezależnie od tego czy proces wykonywany przez serwer zakończył się sukcesem jak w przykładzie poniżej:

< Send a command now.
> Set recognition language to fr
< Done.
< Send a command now.

czy błędem jak w przykładzie poniżej.

< Send a command now.
> Set recognition language to xx
< Error: One or more arguments are invalid
< Send a command now.

Bezpośrednio po nawiązaniu połączenia przez klienta serwer wysyła dwa komunikaty. Pierwszy z nich jest formą powitania, drugi jest opisywanym powyżej zaproszeniem.

< SILVERCODERS OCR Server
< Send a command now.

Zazwyczaj bezpośrednio po poprawnym wykonaniu komendy serwer wysyła do klienta jej wynik, jak w przykładzie poniżej:

< Send a command now.
> Get serial number
< FFFF-1111-2222-3333-4444
< Send a command now.

lub komunikat "Done." jeśli wykonano komendę nie zwracającą żadnego wyniku, jak w przykładzie poniżej.

< Send a command now.
> Set image format to jpeg
< Done.
< Send a command now.

4.2. Get server version

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

< Send a command now.
> Get server version
< 1.0.3
< Send a command now.

4.3. End session

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

< Send a command now.
> End session
< Bye.

4.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.

< Send a command now.
> Set protocol version to 1
< Done.
< Send a command now.

4.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.

< Send a command now.
> Set messages language to fr
< Done.
< Send a command now.

4.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.

< Send a command now.
> Set recognition language to fr
< Done.
< Send a command now.

4.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.

< Send a command now.
> Upload document
< Send file now.
> Extension: tif
> Size: 25276245
> Checksum: 38421
> --- DANE PLIKU ---
< Page: 0
> Continue
< Page: 1
> Continue
< Page: 2
> Continue
< Page: 3
> Continue
< Done.
< Send a command now.

4.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.

< Send a command now.
> Get number of pages
< 3
< Send a command now.

4.9. Set image width to

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

< Send a command now.
> Set image width to 300
< Done.
< Send a command now.

4.10. Set image height to

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

< Send a command now.
> Set image height to 200
< Done.
< Send a command now.

4.11. Set image format to

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

< Send a command now.
> Set image format to jpeg
< Done.
< Send a command now.

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

4.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.

4.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).

4.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.

4.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.

4.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.

4.12. Enable page breaks in plain text

Gdy ta komenta zostanie wysłana OCR Server włączy podział na strony w tekście niesformatowanym zwracanym przez komendę "Export document as plain text". Do oddzielenia stron używany jest znak "form feed" (0xC heksadecymalnie).

< Send a command now.
> Enable page breaks in plain text
< Done.
< Send a command now.

Ta komenda wymaga serwera w wersji 1.0.2 lub późniejszej.

4.13. Get image of page

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

< Send a command now.
> Get image of page 0
< Done.
< Extension: jpg
< Size: 144628
< Checksum: 33381
< --- DANE PLIKU ---
< Send a command now.

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".

4.14. Recognize page

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

< Send a command now.
> Recognize page 0
< Progress: 0
> Continue
< Progress: 0
> Continue
< Progress: 0
...
< Progress: 1
> Continue
< Progress: 19
> Continue
< Rect: 2376 134 2526 222
> Continue
< Tip: Increase resolution to improve recognition accuracy of small text.
> Continue
< Progress: 19
> Continue
< Rect: 332 372 480 418
...
< Progress: 100
> Continue
< Done.
< Send a command now.

4.15. Export document as

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

< Send a command now.
> Export document as plain text
< Progress: 0
> Continue
< Progress: 0
> Continue
< Progress: 25
> Continue
< Progress: 50
> Continue
< Progress: 75
> Continue
< Progress: 100
> Continue
< Done.
< Extension: txt
< Size: 8533
< Checksum: 46941
< --- DANE PLIKU ---
< Send a command now.

Obsługiwane są poniższe formaty eksportu:

4.15.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.

4.15.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.

4.15.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.

4.15.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.

4.16. 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.

4.16.1. Get serial number

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

< Send a command now.
> Get serial number
< FFFF-1111-2222-3333-4444
< Send a command now.

4.16.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).

< Send a command now.
> Get counter measure unit
< pages
< Send a command now.

4.16.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.

< Send a command now.
> Get limitation period
< month
< Send a command now.

4.16.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.

< Send a command now.
> Get units per period
< 10000
< Send a command now.

4.16.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.

< Send a command now.
> Get remaining units
< 9997
< Send a command now.

4.16.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.

< Send a command now.
> Get expiration date
< none
< Send a command now.

4.17. 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.

4.17.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

4.17.2. Dane pliku

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

4.17.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;
}

4.18. Raportowanie i kontrola postępów operacji

Niektóre polecenia takie jak "Recognize page" lub "Export document as" rozpoczynają proces, który może być dość czasochłonny. Aby zagwarantować możliwość implementacji przyjaznych dla użytkownika aplikacji klienckich, protokół daje możliwość raportowania postępów tego rodzaju operacji oraz anulowania ich na żądanie.

4.18.1. Raportowanie postępów w procentach

OCR Server raportuje postęp czasochłonnych operacji w procentach. Wartość procentowa jest wartością całkowitą z przedziału 0..100. Każda z wartości może być raportowana więcej niż raz.

< Progress: 0
> Continue
< Progress: 0
> Continue
< Progress: 25
> Continue
< Progress: 50
> Continue

Funkcja ta jest często wykorzystywana do implementacji paska postępu w aplikacji klienckiej.

4.18.2. Raportowanie bieżacej strony

Podczas czasochłonnych wielostronicowych operacji OCR Server raportuje numer bieżącej strony. Numer strony jest liczbą całkowitą większą lub równą 0. Każda z wartości może być raportowana tylko jeden raz.

< Page: 0
> Continue
< Page: 1
> Continue
< Page: 2
> Continue

Funkcja ta jest często wykorzystywana w celu pokazania postępu operacji w aplikacji klienckiej.

4.18.3. Raportowanie bieżacego regionu obrazu

Podczas czasochłonnych wieloregionowych operacji OCR Server raportuje współrzędne bieżącego regionu. Współrzędne bieżącego regionu składają się z czterech (lewy, górny, prawy, dolny róg) wartości całkowitych rozdzielonych spacjami. Jednostką wartości jest piksel.

< Progress: 19
> Continue
< Rect: 2376 134 2526 222
> Continue

Funkcja ta jest często wykorzystywana do oznaczenia aktualnie przetwarzanego regionu na podglądzie dokumentu w aplikacji klienckiej.

4.18.4. Porady dotyczące rozpoznawania

OCR Server raportuje ważne wskazówki, które mogą poprawić jakość rozpoznawania. Tego typu wiadomości powinny zostać przedstawione użytkownikowi w aplikacji klienckiej.

< Progress: 19
> Continue
< Tip: Increase resolution to improve recognition accuracy of small text.
> Continue
< Progress: 19
> Continue

4.18.5. Kontynuowanie lub anulowanie procesu

Po wysłaniu informacji o postępie lub wskazówki dotyczącej rozpoznawania, OCR Server czeka aż aplikacja kliencka wyśle polecenie "Continue". Polecenie to potwierdza, że interfejs użytkownika został zaktualizowany, użytkownik nie przerwał operacji i proces rozpoznawania może być kontynuowany.

Zamiast potwierdzenia, do OCR Servera może być wysłane polecenie "Cancel". Polecenie to prosi serwer o przerwanie bieżacej operacji.

< Progress: 0
> Continue
< Progress: 1
> Cancel
< Error: The operation was canceled.
< Send a command now.

Funkcja ta jest często wykorzystywana do implementacji przycisku "Anuluj" w aplikacji klienckiej.

4.18.6. Reportowane o zakończeniu procesu

Po pomyślnym zakończeniu procesu OCR Server wysyła wiadomość "Done.".

< Progress: 99
> Continue
< Progress: 100
> Continue
< Done.
< Send a command now.

4.19. Reportowanie błędów

Istnieją dwa rodzaje błędów, o których wystąpieniu może powiadomić OCR Server. Standardowe błędy dotyczą jedynie aktualnie wykonywanej operacji i po wysłaniu odpowiedniej informacji serwer jest gotowy do wykonywania innych poleceń. Po wystąpieniu błędu krytycznego serwer przerywa połączenie i kończy działanie.

OCR Server sygnalizuje standardowe błędy wysyłając wiadomość rozpoczynającą się od wyrażenia "Error:". Błędy krytyczne sygnalizowane są wiadomością rozpoczynającą się od wyrażenia "Fatal error:".

< Send a command now.
> Set recognition language to xx
< Error: One or more arguments are invalid