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.

Pobierz Bbo
Pobiera z sieci turnieje brydżowe (lub zestawy rozdań) zapisane na serwerze BBO 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.4

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.

Niektóre pliki rozpowszechniane są na bardziej liberalnej licencji MIT, ale dotyczy to tylko tych plików, które zawierają nagłówek MIT.

2.1 Dołączone programy

Program korzysta z następującego oprogramowania:

Apache HttpClient
Apache HttpClient to biblioteka klienta protokołu HTTP.

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.

Kotlin
Kotlin Język programowania wywodzący się z Javy.

Logback i SLF4J
Logback SLF4J Biblioteki do generowania logów 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:

wget
wget for windows, z dystrybucji Msys2, to narzędzie do rekursywnego ściągania stron www, wraz ze wszystkimi potrzebnymi plikami. Pliki z licencją: wget_COPYING.txt, wget_README.txt. binaries and dependencies,

Ten dokument html został wygenerowany przy użyciu translatora LaTeX2HTML.

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

3 Funkcjonalność

Funkcjonalności Pobierz... dostępne są przez przycisk Pobierz rozdania. Dalej możemy wybrać rodzaj turnieju lub tylko wpisać link i zostawić opcję wykryj-automatycznie.


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

Bridge Base Online to najpopularniejszy serwer do sieciowej gry w brydża. Spotkać tam można światowej klasy sławy, również polską czołówkę. Rozegrane turnieje czy rozdania można analizować poprzez stronę www, na której przechowywane są wszystkie rozdania. Kłopotliwe jest jednak np. przeanalizowanie licytacji lub wistu na wszystkich stołach. Dzięki ściągnięciu turnieju do pliku PBN, można wygodnie analizować turniej w swoim lokalnym programie brydżowym. Podczas otwierania takiego pliku w Jacku, bardzo szybko można przejrzeć te elementy (licytacja, rozgrywka) na wszystkich stołach.

Innym zastosowaniem ściągniętych z Bbo plików będzie rozegranie rozdań z turnieju, który odbył się w internecie. Jest to o tyle lepsze od rozegrania turnieju z Kopsa, że w pliku PBN będziemy mieć także licytację i rozgrywkę ze wszystkich stołów. Tak dokładnej informacji Kops nam nie dawał.

Obciążenie serwera Bbo przy zastosowaniu ściągania przez PbnTools jest niewielkie. Tyle, co byśmy kliknęli po kolei w każdego travellera.

3.3.1 Pobieranie turnieju

Użyj opcji Pobierz rozdania / Typ rozdań: Bbo.

Który dokładnie link wkleić do PbnTools? Na stronie Bbo wchodzimy w Hand Records, następnie results of recent tournaments. Dalej np. Pairs. Właściwym linkiem jest boards. Przykładowy link do turnieju Bbo wygląda tak: 

  https://www.bridgebase.com/myhands/hands.php?tourney=1234-1234567890-

Efektem działania tej opcji programu są m.in. następujące pliki, umieszczane w katalogu zgodnym z nazwą turnieju, pod katalogiem roboczym:

  • XXX.pbn - plik z rozdaniami i wynikami
  • hands.php?tourney....html - lista travellerów
  • hands.php?traveller....html - travellery
  • *.lin - pliki lin (format Bbo), jeden na rozdanie
  • link.html - zawiera link do oryginału turnieju, ułatwiający analizę porozdaniową

3.3.2 Pobieranie historii rąk

Użyj opcji Pobierz rozdania / Typ rozdań: Bbo Hand records.

Link do historii rąk uzyskujemy po naciśnięciu Get hands na ekranie Hand records. Przykładowy link: 

  https://www.bridgebase.com/myhands/hands.php?username=playersnick&start_time=1617573600&end_time=1617746400


3.4 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.4.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.5 Konwersja LIN na PBN

Konwersji z formatu LIN na PBN można dokonać z interfejsu graficznego lub z linii poleceń.


3.6 Konfiguracja

Katalog roboczy
Podczas pobierania rozdań 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.
User agent
User agent to tekst, którym przedstawia się przeglądarka internetowa serwerowi, z którym się łączy, np. Firefox/25.0. Wersja PbnTools poniżej 1.2.0 przedstawiała się jako Java, a to powodowało, że niektóre serwery nie zezwalały na połączenie, błąd 403. Od wersji 1.2.0 domyślny tekst User agent to PbnTools/1.2.0. Dzieje się tak, gdy parametr jest pusty. Jeżeli wpiszemy tu jakiś tekst to, będzie on użyty zamiast PbnTools i numeru wersji. To tak na wszelki wypadek, gdyby serwery rozmyślnie lub przypadkiem blokowały PbnTools.
Czas zwłoki www
Pomiędzy kolejnymi żadaniami pobrań stron www należy zachować pewien odstęp czasu, żeby nie przeciążać serwera. Staramy się przy tym sprawiać wrażenie, że robi to istota ludzka, a nie automat. Polskie serwery działają poprawnie przy czasie 1 sekundy, ale serwer Bbo wymaga 3 (a nawet 4) sekund, bo inaczej zwraca błędy 503. Podajemy liczbę sekund, minimalna wartość: 1.


3.7 Opcje linii poleceń

Część funkcjonalności programu dostępna jest w trybie linii poleceń, czyli bez uruchamiania graficznego interfejsu użytkownika (okienek dialogowych). Na przykład pobrać turniej można albo uruchamiając program i następnie klikając Pobierz turniej Kops, albo uruchamiając program w następujący sposób: 

    pbntools -dtk http://www.strona-turniejow.pl/turniej999/index.html

Opcje linii poleceń można uruchamiać również poprzez bezpośrednie uruchomienie pliku jar, przykładowo: 

    java -jar PbnTools.jar -dtk http://www.strona-turniejow.pl/turniej999/index.html

Z linii poleceń dostępne są następujące opcje:

  • -h Wyświetla krótki opis wszystkich opcji.
  • ---debug Włącza tryb debuggowania, z wyświetlaniem informacji, które mogą pomóc w diagnostyce nieprawidłowego działania programu.
  • ---verbose Zwiększa ilość informacji wyświetlanej przez program, np. podczas pobierania turnieju.
  • -dtb <link> Pobiera turniej w formacie Bbo ze wskazanego linku. Turniej zapisywany jest w katalogu roboczym, tak samo jak przy użyciu interfejsu graficznego.
  • -dtbh <link> Pobiera historię rąk w formacie Bbo ze wskazanego linku.
  • -dtk <link> Pobiera wskazany turniej w formacie Kops.
  • -dtp <link> Pobiera wskazany turniej w formacie Pary.

3.8 Opcje poprzez parametry Java

Dodatkowej konfiguracji programu można dokonywać poprzez konfigurację właściwości maszyny wirtualnej Java (JVM). Dostępne są następujące opcje:

jsoup.log.folder
Katalog, do którego zapisywane będą wszystkie pliki pobierane z internetu przez bibliotekę JSoup. Przydatne w celach diagnostycznych.
user.language Wymuszenie języka komunikatów (pl lub en).

Przykładowe uruchomienie programu z zastosowaniem właściwości JVM: 

  java -Djsoup.log.folder=C:/temp/bbo-jsoup -jar PbnTools.jar -dtk http://www.strona-turniejow.pl/turniej999/index.html

4 Wymagania

Wymagana jest Java w wersji 6. Ze względu na wykorzystanie programu 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.3.3:

Poprzednie wersje: 1.3.2: Windows Linux , 1.3.1: Windows Linux , 1.3.0: Windows Linux , 1.2.7: Windows Linux , 1.2.6: Windows Linux , 1.2.5: Windows Linux , 1.2.4: Windows Linux , 1.2.3: Windows Linux , 1.2.2: Windows Linux , 1.2.1: Windows Linux , 1.2.0: Windows Linux , 1.1.0: Windows Linux


5.2 Kody źródłowe

Źródła bibliotek Apache HttpClient, Kotlin można pobrać z repozytorium mavena. Może się to odbyć automatycznie podczas budowania projektu narzędziem gradle.

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 w Javie.

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. JUnit, JUnit-addons - do wykonania autotestów.

7 Historia wersji programu

1.3.3, 22.05.2021
  • Usprawnienie pobierania - automatyczne ponawianie po błędzie http 503
1.3.2, 20.05.2021
  • Poprawka do pobierania historii rąk Bbo
  • Upgrade wget na windows do wersji 1.20.3-2 msys
1.3.0, 06.04.2021
  • Bbo - możliwość pobierania historii rąk (nie tylko turniejowych)
  • Bbo - poprawki dotyczące innego zapisu rozdań (większe zapisy lin)
1.2.7, 09.11.2020
  • Linki bbo są teraz https.
1.2.6, 18.05.2020
  • Naprawa problemu wget z certyfikatami.
  • Plik logu, pomocny przy rozwiązywaniu problemów (%USERPROFILE%/.PbnTools/PbnTools.log).
1.2.5, 04.04.2020
  • Zapisywanie ekranu wyniku logowania do BBO.
1.2.4, 12.04.2018
  • Komunikaty przy nieudanym logowaniu do BBO.
1.2.3, 17.03.2018
  • Generowanie plików results.csv i results_ranked.csv, separator średnik.
1.2.2, 12.03.2018
  • Pobieranie z BBO z logowaniem (obowiązkowe).
  • Generowanie pliku results.csv przy pobieraniu z BBO (eksperymentalnie).
1.2.1, 27.11.2013
  • Usunięto błędy.
1.2.0, 24.11.2013
  • Pobieranie turniejów Bbo.
  • Konwerter z lin na pbn.
  • Opcja User agent w oknie konfiguracyjnym.
  • Nowa opcja konfiguracyjna: czas zwłoki www.
  • Usprawnienie pobierania turniejów Pary, był np. problem z polem „frameset”.
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 22.05.2021