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.

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

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

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.

JSoup
JSoup JSoup to biblioteka javy do pracy z rzeczywistymi plikami HTML. Rzeczywistymi, to znaczy takimi, które niekoniecznie są w pełni poprawnie sformatowane. JSoup dostarcza wygodnego API do wydobywania i manipulowania danymi, używając metod typu DOM, CSS i jquery. Patrz plik: jsoup_LICENSE.txt w katalogu programu.

ZBar
ZBar (lub jej klon ZBarW) 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.

Uwaga do pobierania linków z warszawskiego serwera warsbrydz:
Po wejściu w Wyniki i wybraniu cyklu, nie wybierajcie od razu turnieju. Zamiast tego wybierzcie Stare. Otrzymacie staromodną listę turniejów i teraz już normalnie: prawy przycisk, kopiuj adres odnośnika (to na Firefoxie, na innej przeglądarce będzie nieco inaczej, ale w ten deseń) i wkleić do PbnTools. Teraz już zadziała.

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

  • XXX_wyn.pbn - plik z rozdaniami i wynikami - na podstawie tego pliku generujemy turniej w Jacku
  • XXX.pbn - plik z rozdaniami turnieju (XXX to nazwa turnieju, np. MCH0308)
  • roz.html - lista travellerów całego turnieju
  • link.html - zawiera link do oryginału turnieju, ułatwiający analizę porozdaniową
  • pNN.html - traveller dla rozdania o numerze NN

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 Pobierz Pary

Pary to również program Jana Romańskiego, który miał zastąpić Kopsa, a ostatecznie funkcjonuje równolegle z nim. Turnieje wygenerowane tym programem poznać po stopce Pary.4.1.0.23 (C) Jan Romański'2005, strona wygenerowana .... Turnieje takie można znaleźć na przykład wśród wyników turniejów na stronie warsbrydz, cykl WOB. Linki otrzymujemy po wybraniu pseudoturnieju Stare, a następnie już normalnie - prawy przycisk, Kopiuj adres odnośnika.

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

  • XXX.pbn - plik z rozdaniami i wynikami
  • AAyymmddnnn.html - travellery poszczególnych rozdań. Każdy z nich stanowi jednocześnie indeks umożliwiający przejście do pozostałych rozdań turnieju.
  • link.html - zawiera link do oryginału turnieju, ułatwiający analizę porozdaniową
  • inne pliki potrzebne dla prawidłowego wyświetlenia stron html


3.3 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.3.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.4 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.1.0:

Poprzednie wersje: 1.0.0: Windows Linux , 1.0.1: Windows Linux , 1.0.2: Windows Linux , 1.0.3: Windows Linux


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. launch4j, do utworzenia pliku exe dla Windows.
  5. Latex, do dokumentacji. nazwa pakietu w Debianie: latex2html.
  6. 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.1.0, 16.09.2012
  • Pobieranie turniejów w formacie Pary. Na przykład ze strony warsbrydz , Wyniki, WOB, stare.
  • Zmiana biblioteki video używanej do rozdawania kart pod Windows, zastosowanie sterownika DirectShow w miejsce Video for Windows. Powinno to usunąć większość problemów, z którymi borykali się użytkownicy Windows, czyli nie uruchamiająca się w ogóle kamera lub jej zawieszanie.
1.0.3, 05.04.2012
  • Opcja Sprawdź uaktualnienie w oknie O programie.
  • Modyfikacja zbara, który wcześniej nie radził sobie z kamerami dostarczającymi obraz w formacie MJPG.
  • Uwidocznienie aplikacji na pasku zadań.
1.0.2, 01.11.2011
  • Poprawka formatu PBN: było błędnie 10 zamiast T.
1.0.1, 01.11.2011
  • Ignorowanie pliku robots.txt podczas pobierania turniejów.
1.0.0, 01.11.2011
Pierwsze oficjalne wydanie i ustanowienie licencji GNU GPL 3.0.
  • Opcja Rozdaj
0.5, 07.03.2010
Wersja prywatna, nierozpowszechniana publicznie.
  • Obsługa opcji Pobierz kops.

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 16.09.2012