PbnTools - pomoc


Spis treści

1 Wstęp

PbnTools to w zamyśle zestaw narzędzi do plików z zapisanymi rozdaniami brydżowymi. Najpopularniejszy format tych plików to PBN.

Obecnie PbnTools posiada następujące funkcjonalności:

Pobierz Kops
Pobiera z sieci turnieje brydżowe zapisane w formacie Kops i zapisuje je w formacie PBN. Szczegóły: 3.1.

Rozdaj
Po otwarciu dowolnego pliku PBN można go rozdać, czyli rozdzielić prawdziwe papierowe karty na 4 kupki, powielając oryginalny układ. Osoba rozdająca nie zaznajamia się z kartami, gdyż w rozdawaniu pomaga kamera internetowa. Karty muszą być oznakowane kodami paskowymi. Szczegóły: 3.2

Program uruchamia się otwierając plik PbnTools.exe (Windows) lub pbntools (linux).

2 Licencja

Program rozpowszechniany jest wraz z kodem źródłowym na licencji GNU GPL, wersja 3 lub późniejsza. Oznacza to, że można go bezpłatnie pobrać, używać, a nawet modyfikować na własne potrzeby. Rozpowszechnianie wymaga już spełnienia warunków licencji, która ważna jest tylko w języku angielskim. Krótki opis licencji, jak również link do nieoficjalnego tłumaczenia licencji GNU GPL można znaleźć w wikipedii.

2.1 Dołączone programy

Program korzysta z następującego oprogramowania:

JLayer
JLayer to biblioteka dla JavyTM, które dekoduje, konwertuje i odtwarza pliki MP3. Rozpowszechniana na licencji LGPL. Patrz pliki: jlayer_LICENSE.txt i jlayer_README.txt w katalogu programu.
ZBar
ZBar to biblioteka o funkcjonalności czytnika kodów paskowych, rozprowadzana na licencji LGPL 2.1 (lub późniejsza). Czyta pliki graficzne lub obraz z kamery internetowej. Zastosowana została tutaj okrojona wersja odczytująca obraz z kamery. Plik z licencją: zbar_LICENSE.txt

Wersja Windows korzysta także z:

msys
Środowisko skryptowe z Linuxa działające pod Windows, a więc przede wszystkim bash. Wykorzystana jest część plików z wersji 1.0.11. Kompletny pakiet binarny: msysCORE-1.0.11-bin, wget-1.12-1-msys-1.0.13-bin.tar.lzma.

Msys będąc pakietem wielu różnych programów nie ma jednej licencji. Sprawa opisana jest na stronie msys, w sekcji Licensing Terms. Po pobraniu pliku z kodem źródłowym można zapoznać się ze szczegółami licencji poszczególnych komponentów.

wget
wget for windows, z serii GnuWin32, to narzędzie do rekursywnego ściągania stron www, wraz ze wszystkimi potrzebnymi plikami. Plik z licencją: wget_COPYING.txt. binaries, dependencies

Kody źródłowe dostępne są w dziale Pobieranie (5.2).

3 Funkcjonalność


3.1 Pobierz Kops

Kops to program napisany przez Jana Romańskiego, używany do prowadzenia turniejów brydżowych. Umożliwia on również zapis wyników turniejów w formacie html, w którym później są one publikowane, m.in. na stronach Polskiego Związku Brydża Sportowego (PZBS). Wśród wyników prezentowanych przez Śląski Związek Brydża Sportowego największą popularnością wśród najlepszych graczy regionu cieszą się turnieje oznaczone Chorzów.

Lista rozdań wraz z wynikami zapisywana jest do jednego pliku z rozszerzeniem PBN. Pobrany plik PBN można następnie załadować do programu brydżowego i utworzyć na jego podstawie turniej. Utworzony w ten sposób turniej można rozegrać z komputerem lub innym użytkownikiem poprzez sieć. Funkcjonalności te posiada np. program Jack. Jack ma w Polsce promocyjną cenę i dostępny jest u Krzysztofa Jassema

Program wymaga podania linku do turnieju. Chodzi tu dokładnie o link o nazwie Wyniki, który prowadzi do dwuczęściowego ekranu: z wynikami turnieju i rozkładami rozdań. Wygenerowane pliki umieszczone zostają w katalogu wyjściowym (Konfiguracja) w podkatalogu kops. Podkatalog utworzony zostanie automatycznie.

Efektem działania tej opcji programu są następujące pliki:

Efektem ubocznym działania tej funkcji jest również zapisanie w katalogu roboczym kompletnej strony z wynikami turnieju. Po wrzuceniu tego katalogu np. na komórkę, można potem wygodnie analizować rozdania tuż po ich rozegraniu.


3.2 Rozdaj

Rozdawanie polega na pokazywaniu kart do kamery internetowej, która "odnajduje" tę kartę w danym rozdaniu i wskazuje, komu ją przydzielić. Wskazanie odbywa się poprzez wyświetlenie symbolu gracza i wypowiedzenie go przez głośnik. Dla łatwiejszego rozpoznawania gracza sygnały głosowe zostały zastąpione liczbami, to znaczy gracz N to "jeden", E to "dwa" itd.

3.2.1 Wymagania

Kamera internetowa
Najlepsza jest kamera z ręczną regulacją ostrości, czyli "z kółkiem". Koszt około 40 zł. Poprzez uruchomienie programu zbarcam (katalog bin) spoza PbnTools należy dostosować ostrość kamery tak, aby później w ciemno wiedzieć, w jakiej odległości należy umieścić kartę, by kamera najszybciej ją rozpoznała.

Nie wiem, czy sprawdzą się kamery ze stałym focusem. Kamery z autofocusem mogą wymagać dalszego dostosowania programu zbarcam, który obecnie nie ma opcji włączania / wyłączania autofocusa na żądanie. Mógłbym się tym zająć, gdybym miał kamerę z autofocusem do testów.

Karty z kodami paskowymi
Spotkałem się z 2 sposobami oznaczania kart kodami paskowymi. Oba opatentowane są przez firmę Jannersten. Starszy format to DOS, który składa się z 3 czarnych pasków różnych grubości. Nowszy to WIN. Poznać go po cienkich czarnych paskach ograniczających kod z obu stron. Liczba pasków jest różna, ale zawsze większa niż 3. PbnTools obsługuje tylko standard WIN. Karty okodowane w ten sposób można dostać w każdym specjalistycznym sklepie brydżowym, w cenie od 6 zł. Wystarczy wpisać w google sklep brydżowy. Karty wyglądają tak.

Podczas testów z moimi kartami wpadłem w interesującą pułapkę. Mianowicie nagle ni stąd, ni zowąd, program rozpoznawał kartę król karo. Okazało się, że król kier ma króla karo we włosach, a dokładniej jego kod. Trzeba więc było włoski trochę przemalować, mazakiem. I odtąd już było dobrze.


3.3 Konfiguracja

Katalog roboczy
Podczas pobierania turniejów będą tu tworzone podkatalogi z poszczególnymi turniejami.
Opcje dla zbarcam
Dodatkowe opcje przekazywane do programu zbarcam. Dzięki temu można wskazać urządzenie video, jeżeli jest ich w systemie więcej, np.: /dev/video1. Domyślnym urządzeniem jest urządzenie nr 0, czyli pierwsze. Pełna lista opcji dla zbarcam dostępna jest w pliku zbarcam.html.

4 Wymagania

Wymagana jest Java w wersji 6. Ze względu na wykorzystanie programów bash oraz zbar wymagane są systemy operacyjne Windows lub Linux. Programy zewnętrzne zawarte są w pliku instalacyjnym i instalowane są automatycznie.


5 Pobieranie


5.1 Wersje instalacyjne

Aktualna wersja, 1.0.2:


5.2 Kody źródłowe

5.3 Instalacja

Instalacja polega na rozpakowaniu pliku zip do dowolnego nowego folderu. Ten folder stanie się katalogiem programu PbnTools. Uruchomiać należy plik pbntools z tego katalogu.

Folder instalacyjny, jak również wszelkie katalogi używane w programie, nie mogą zawierać spacji. Odpada więc np. katalog "Program Files".


6 Rozwój

Mam nadzieję, że program stanowi niezłą bazę do rozwoju w kierunku wielofunkcyjnego przybornika brydżowego. Sam nie dam rady doprowadzić go do pełnej postaci, dlatego postanowiłem udostępnić go na licencji umożliwiającej dalszy rozwój, w grupie programistów. Liczę na to, że znajdą się wśród Was chętni do ulepszania go. Nawet jeżeli nie jesteś programistą, możesz pomóc poprzez zgłaszanie błędów, uwag lub sugestii.

Program napisany jest głównie w Javie, aczkolwiek są jeszcze relikty w bashu, które mam nadzieję z czasem usunąć.

Do dyspozycji mamy następujące narzędzia:

Szczegóły pracy nad kodem źródłowym dostępne są w pliku README.SRC.txt, w archiwum kodu źródłowego, patrz: Pobieranie, 5.

6.1 Wymagania do budowania

  1. Sun Java Development Kit, JDK 1.6.
  2. ant, nazwa pakietu w Debianie: ant. Główne narzędzie do budowania.
  3. BeanShell, bsh-2.0b4.jar (lub nowszy) wskazany w build.xml
  4. Latex, do dokumentacji. nazwa pakietu w Debianie: latex2html.
  5. Narzędzia do budowania zbara opisane są w plikach źródłowych tego pakietu. Do budowania PbnTools nie jest jednak konieczne ponowne budowanie zbara.

7 Historia wersji programu

1.0.2, 01.11.2011
1.0.1, 01.11.2011
1.0.0, 01.11.2011
Pierwsze oficjalne wydanie i ustanowienie licencji GNU GPL 3.0.
0.5, 07.03.2010
Wersja prywatna, nierozpowszechniana publicznie.

8 Zakończenie

Jestem otwarty na sugestie. Będę wdzięczny za informacje o nieprawidłowym działaniu strony lub programu.

Jarek Czekalski, ostatnia modyfikacja 30.10.2011