PiRO — Projekt 1


Projekt 1 – dopasowywanie elementów ∞

Opis ∞

Opis projektu oraz przykładowych sposobów jego rozwiązania przygotowany w formie pdf jest dostępny tutaj.

Specyfikacja formalna ∞

Celem jest napisanie programu który dopasuje do siebie pasujące elementy. Programy muszą dać się uruchomić na komputerze w laboratorium. Program nie ma wymagać żadnej interakcji z użytkownikiem, a na standardowe wyjście powinien wypisać tylko i wyłącznie odpowiedź zgodną z przedstawioną niżej specyfikacją.

Wejście ∞

Program będzie wywoływany z linii komend z dwoma parametrami:

  1. Ścieżką do katalogu z plikami – path
    Może to być ścieżka względna lub bezwzględna.
    Do operacji na ścieżkach proszę używać biblioteki os.path lub pathlib a nie zwykłych operacji na stringach które w bardzo wielu wypadkach powodowały problemy z działaniem programów!

  2. Liczbą obrazków do wczytania – N
    Uwaga: w katalogu może znajdować się więcej obrazków – należy je zignorować.

W podanym katalogu path będą znajdowały się pliki o nazwach k.png gdzie k jest liczbą z zakresu 0…N-1. (np. 1.png, 12.png, lub 123.png)
Każdy plik k.png jest obrazkiem jednokanałowym zawierającym jedną figurę (pojedynczy fragment przeciętego prostokąta). Tło ma wartość 0, obiekt ma wartość 255, ale możliwe są wszystkie wartości z zakresu 0-255 (na brzegach figury wynikające np. z interpolacji przy obracaniu lub skalowaniu). Obiekt nie będzie stykał się z krawędzią obrazu.

Wyjście ∞

Na standardowe wyjście program powinien wypisać N linii. W i-tej linii (licząc od zera: 0..N-1) powinna znaleźć się przynajmniej jedna liczba mówiąca z którym elementem należy sparować i-ty obrazek.
Można (i najlepiej właśnie tak zrobić bo potencjalnie można uzyskać więcej punktów) aby w każdej linii wypisać więcej liczb (maksymalnie N-1) przedstawiający ranking najbardziej prawdopodobnych dopasowań. Pierwsza liczba w linii określa numer obrazka najbardziej podobnego, druga liczba – drugiego co do podobieństwa, itd.
Każde dopasowanie elementu będzie ocenione na 1/j, gdzie j to miejsce na którym jest poprawna wartość w zwróconym rankingu. W przypadku gdy w danym wierszu nie będzie poprawnej odpowiedzi (tzn. program nie wypisze pełnego rankingu), zakładać się będzie, że program wytypował dany obrazek jako najmniej prawdopodobny.
Warto zwrócić uwagę, że powyższy wzór oznacza, że za każde pojedyncze dopasowanie dostaje się co najmniej 1/(N-1) punktu.

Przykład (hipotetyczny) ∞

Uruchomienie:
python program.py sciezka/do/katalogu 6
Na wyjściu może pojawić się np. takie wyjście:

1 2 3 4
0 2 3 4 5
0 1 3 4 5
4 0 1
1 0
0 1 2 3

Oznacza ono, że obrazek 0.png powinien być dopasowany do obrazka 1.png, 1.png do 0.png, 2.png do 0.png, 3.png do 4.png, 4.png do 1.png, a 5.png do 0.png.

Przykładowe dane ∞

Przykładowe zestawy danych:

W każdym katalogu z przykładowymi danymi jest dodatkowo plik correct.txt zawierający prawidłowe wyjście (tylko jedna poprawna liczba w wierszu).
Obrazki zostały wygenerowane zupełnie losowo bez sprawdzania ich poprawności czy jednoznaczności dopasowania. W razie wykrycia jakiś problemów proszę o informację.

Programy docelowo będą sprawdzane na innych zbiorach danych, również na takich w których obrazki zostaną poddane innym transformacjom (np. perspektywicznym), ale ogólnie powinny być raczej zbliżone do zaprezentowanych.

Zaliczenie projektu ∞

Projekt powinien być wykonany w zespole maksymalnie dwuosobowym.
Projekt oceniany będzie na podstawie:

  1. Wyników na zbiorach testowych.

  2. Krótkiego opisu metody (ok 2-3 strony) zawierającego:

    • poszczególne kroki przetwarzania obrazków wejściowych (może to być dosłownie wypunktowanie kolejnych kroków)

    • sposób porównywania ze sobą elementów, czyli:

      • jak opisywany jest pojedynczy fragment (jego reprezentacja),
      • jak takie opisy są ze sobą porównywane.

    Oczywiście opis metody należy odpowiednio dopasować w zależności od zaimplementowanego rozwiązania.

Ostateczny termin przysłania rozwiązania (program + krótki opis): 30 kwietnia

Wymagania dotyczące przysyłanego programu ∞

Poniższy tekst będzie jeszcze aktualizowany i dostosowywany do aktualnego stanu komputerów w 1.6.21

Proszę przygotować dwa lub trzy (szczegóły niżej) pliki o nazwach zgodnych ze wzorcem:

  • w przypadku projektów robionych indywidualnie: piro1_<indeks1>.<rozszerzenie>,
  • w przypadku projektów robionych w parach: piro1_<indeks1>_<indeks2>.<rozszerzenie>,

gdzie zamiast <indeks1> oraz <indeks2> należy wstawić numer indeksu odpowiednio pierwszego oraz drugiego autora, a <rozszerzenie> oznacza odpowiednie rozszerzenie podane poniżej.

Uwaga! Pliki nazwane inaczej nie będą poprawnie przetworzone przez skrypt!

Wymagane pliki:

  1. rozszerzenie src.tar.bz2 — archiwum ze źródłami projektu wraz z jednym plikiem Dockerfile
  2. rozszerzenie pdf — plik pdf ze sprawozdaniem

  3. [opcjonalny] rozszerzenie img.tar.bz2 — skompresowany obraz dockera zbudowany i przetestowany przez Państwa.
    Obraz powinien być nazwany wg schematu: piro1_<indeks1> lub piro1_<indeks1>_<indeks2>
    Jeśli nie będzie tego pliku to skrypt sam stworzy brakujący obraz używając polecenia (dla projektu jednoosobowego):
    docker build -t piro1_<indeks1> - < piro1_<indeks1>.src.tar.bz2
    Powyższe polecenie musi zakończyć się sukcesem na jednej z maszyn w laboratorium 1.6.21, inaczej skrypt założy, że dostarczony projekt jest niepoprawny (w szczególności proszę zwrócić uwagę, że polecenie zakłada, że plik Dockerfile nie jest w żadnym podkatalogu stworzonego archiwum)

Państwa programy będą uruchamiane poleceniem podobnym do:
docker run --network none --mount type=bind,source=moje/dane,target=/tmp/obrazki,readonly piro1_<indeks1> /tmp/obrazki 123

Wymagania dotyczące obrazu dockera:

  • stworzony obraz musi się dać uruchamiać wg. schematu jak podano powyżej

  • należy dodać etykiety student1 oraz (dla projektów dwuosobowych student2) zawierających imię oraz nazwisko pierwszego (oraz drugiego) autora, w pliku Dockerfile należy dodać np.:
    LABEL student1="Adam Kowalski" student2="Monika Nowak"

Dostarczenie plików:

  1. pliki należy wgrać na chmurę PP
  2. następnie mi je udostępnić abym mógł je odczytać (proszę nie generować linków! – patrz uwaga niżej)
  3. wysłać mi maila z tytułem zawierającym indeksy autorów: [PiRO] proj1_<indeks1>_<indeks2>

Instrukcja obsługi chmury PP: https://instrukcje.put.poznan.pl/chmura-politechniki-poznanskiej/
UWAGA — proszę przeczytać sekcję Udostępnianie, a w szczególności zwrócić uwagę na wzór adresu który należy podać:
student dla pracowników – imie.nazwisko@put.poznan.pl@chmura.put.poznan.pl

Przykładowy plik Dockerfile:

FROM python:3.8-slim-buster
WORKDIR /app
#install OpenCV
#RUN pip install --no-cache-dir opencv-python-headless
#install scikit-image
#RUN pip install scikit-image
COPY . .
ENTRYPOINT [ "python3", "proj1.py" ]
LABEL student1="Adam Kowalski" student2="Monika Nowak"

Przykładowy plik proj1.py:

print("5\n2\n1\n4\n3\n0\n")

Przykładowe stworzenie obrazu dockera z zadaną nazwą i zapisanie go do pliku:

docker build . -t piro1_12345_54321
docker save piro1_12345_54321 | bzip2 > piro1_12345_54321.img.tar.bz2

Przykładowe stworzenie archiwum z katalogu z kodem źródłowym:

tar -C katalog/z/kodem -cjvf piro1_12345_54321.src.tar.bz2 .

Przykładowy plik src.tar.bz2

Orientacyjne wyniki dla dostępnych zbiorów ∞

Dla zbiorów set0-set4: średnio 100% punktów
Dla zbiorów set5-set6: średnio >95% punktów
Dla zbiorów set7-set8: średnio 60% punktów