PIRRO
- • Team A
- • Team B
- • Team C
Team_B_Page

Sws
%BEGINLATEXPREAMBLE%
\usepackage{amsmath}
%ENDLATEXPREAMBLE%

Page for Team B slot 15
---+ Hints
You can write tex in twiki like this:
inline:
%$\int_{-\infty}^\infty e^{ -\alpha x^2 } dx = \sqrt{ \frac{\pi}{\alpha} }$%

multiline:
%BEGINLATEX{label="one" color="Green"}% 
\[ A = U \Sigma V^H \]
 %ENDLATEX%

%TOC%

---+ Introduction
---++ Background (from the news)
Archeologists have discovered that the recently recovered fragments from the Scrolls of Oumroum in Egypt may contain the answer to Life, the Universe and Everything. This is indicated by some of the words on the fragments that have been translated out of Koine Greek. The reconstruction of the scrolls is of great importance.

The fragments have already been digitally processed with an automatic analysis system in order to match them. Unfortunately, it turned out that there are many ways in which you can combine the fragments, and the scientists have also observed that most matches are just physical and not logical. The reconstruction has failed until now. As a last effort to unveil the secrets of Oumroum, the scientists requested a collaborative system in which other scientists and passionate people can join forces to solve this puzzle. 

---++ System description and requirements
As the newspaper fragment above indicates, this project is the final effort to decipher the scrolls of Oumroum. Therefore our system has to provide a pleasant working environment for the scientists who are working on the process of putting the pieces together. It has to provide ample communication mechanisms and an intuitive way of putting pieces together. Then it also needs a way of having multiple scientists working together, so we need a consistent way of storing and handling differences in opinions on the composition of the pieces. 

The system should provide:
   * intuitive way of putting pieces together
   * collaborative and private workspaces
   * mechanisms for:
      * saving intermediate work
      * viewing history
      * restoring a previous version of the work
      * combining the work of different scientists
   * suggestions for matching pieces
   *ample communication mechanisms

---+ Stakeholders
The stakeholders involved in the system are:
   * Users
      * Scientist - those who are using the system to solve the puzzle
      * Data providers - the persons who add new pieces to the system
      * Community - passionate people that are not scientists but whom are interested in solving the puzzle
      * Moderators - persons who monitor the communication channels of the system
   * System administrators - have to maintain the system and install updates
   * Sponsors - those whom are funding the project

---+ Definitions
---+++++!!Piece
A piece is a scan of a single physical scroll fragment.
   * Can be disabled/re-enabled (e.g. duplicates)
   * When disabled will be marked in compositions

%$\mathcal{P}$% = the set of all pieces

---+++++!!Composition member
A composition member is a piece along with a position (relative to the origin of the workspace) and a rotation.

%$\mathcal{M}$% = the set of all possible composition members%BR%
%$\mathcal{M} = \{(p,pos,rot)\,|\,p\in \mathcal{P}, pos\in Position, rot\in Double \}$%

%$Position = Double \times Double \times Integer$%

The position includes a z-index which is used to determine how overlapping pieces are displayed.%BR%
A composition member can only be used in one composition.

---+++++!!Annotation
An annotation is a user information that is attached to a composition. Its main purpose is to help users identify compositions and explain their intentions about combining pieces.

%$Annotation = String$%

%$Seq_n\ T = Nat|(\leq n) \to T$%

%$\mathcal{A}$% = the set of all sequences of annotations%BR%
%$\mathcal{A} = \{s\,|\,s :: Seq\,Annotation\}$%

We define the following operations on annotations:

%BEGINLATEX%
 \begin{align*}
&\text{++} :: Seq_n\ Annotation \rightarrow Seq_m\ Annotation \rightarrow Seq_{n+m}\ Annotation \\
&(a \text{++} b) (i) = \begin{cases} 
                a(i) & i \leq n \\
                b(i-n) & \text{otherwise}
             \end{cases}
\end{align*}

 \begin{align*}
&\text{addAnn} :: Seq_n\ Annotation \rightarrow Annotation \rightarrow Seq_{n+1}\ Annotation \\ 
&\text{addAnn}\ ss\ a = \begin{cases}
                ss(i) & i \leq n \\
                a & \text{otherwise}
              \end{cases}
\end{align*}
%ENDLATEX%

---+++++!!Composition
Intermediate combinations of pieces on which the scientists are working  are stored in compositions.%BR%
A composition consists of a set of 0 or more composition members and a sequence of annotations.

%$\mathcal{C}$% = the set of all compositions%BR%
%$\mathcal{C} = \{ (ann, members) \;|\;ann \in\mathcal{A}, members \subset \mathcal{M}\}$%			

---+++++!!Workspace
The work of a group of scientists is modeled using the workspace.%BR%
A workspace is a 2.5-D coordinate system which contains 0 or more compositions. %BR%
The coordinate system, %$CS$%, is described be the following:
   * a point that is the origin, %$O$%
   * positive x axis goes to the right, %$\vec{i}$%
   * positive y axis goes up, %$\vec{j}$%
   * z axis is the cross product of x and y, %$\vec{i}\times\vec{j}$%
%$CS :: ({Real}^2, Vector, Vector, Vector)$% %BR%
%$CS = (O,\,\vec{i},\,\vec{j},\,\vec{i} \times\vec{j})$%

%$\mathcal{W}$% = the set of all compositions from the workspace

---+++++!!Revision
A revision is used to represent a certain version of the work of a group of scientists.%BR%
A revision has:
   * a set of compositions
   * a revision number

%$Revision :: 2^\mathcal{C} \times Nat$% %BR%
%$\mathcal{R}$% = the set of all revisions%BR%
%$\mathcal{R} = \{r\,|\,r::Revision\}$% 

---+++++!!Branch
A branch represents the versioned workspace of a group of scientists.%BR%
A branch is a sequence of revisions of a single workspace.

%$\mathcal{B}$% = the set of all branches%BR%
%$\mathcal{B} = \{s\,|\,s::Seq\,Revision\} $%

---+ Components
   * [[#PieceMgm][Piece management]]  stores individual pieces and their bitmaps
   * [[#VsSys][Versioning system]] keeps track of compositions and their revision history
   * [[#AsS][Automatic Suggestion System (ASS)]]
   * [[#UsrMgm][User management]]
      * Authentication
      * Rights management
      * Group management
   * [[#UsrInterface][User interface]]
      * Compositor
      * Navigation manager
   * [[#CommSys][Communication system]]
      * Direct communication - instant messaging
      * Indirect communication - forum and mail

---++ Component diagram
<img src="%PUBURLPATH%/%WEB%/PIRRO/components.png" alt="Components diagram" width='560' height='400' />

#PieceMgm
---++ Piece management 
Piece management component manages pieces and operation that can be done on them.
It provides the following operations on pieces:
   * =get= retrieves all stored pieces
   * =add= adds a new piece to the system
   * =remove= removes a piece from the system

The component is used by the Compositor which displays the pieces to the user, by the Versioning system which needs the pieces in order to version compositions, and by the ASS when searching for matches.

The =add= and =remove= operations are intended to be used when new scroll pieces are found (=add=) or when duplicate pieces are discovered (=remove=) and only by system administrators.

#VsSys
---++ Versioning system
The Version management system provides a number of operations on compositions and workpaces:
   * =checkout= given a revision number creates a a new workspace from a branch 
   * =update=
      * adds all compositions from newer revisions in the branch to the workspace
      * may result in conflicts
   * =commit=
      * stores the workspace as a new revision in the branch
      * requires conflicts to be resolved first (uniqueness constraint)
      * requires workspace to be up-to-date (same revision as branch)
      * the revision number is the previous revision number increased by 1
   * =import=
      * copies a composition from another branch into workspace
      * may result in conflicts
   * =branch= creates a new branch as a copy of another branch
   * =merge=
      * given two branches imports the compositions of the first into the second
      * in case of conflicts the user is asked to resolve them and the  operation is tried again

#AsS
---++ Automatic Suggestion system
ASS analyses pieces and compositions to find matching between them. Each match is rated with a value (the quality index) between _minQuality_ (no match) and  _maxQuality_ (perfect match).

The ASS specification is given by the following functions: 
   * =matchPiece= given piece returns a list of matching pieces together with quality indices
   * =matchComposition= searches the specified version of the workspace for matches with the specified piece and returns all matches together with their quality index
   * =qualityInterval= returns the matching quality interval %$[minQuality,\,maxQuality]$%
 
This component is used from the Compositor. Users can perform searches for matches between pieces or compositions. The result is a list with the corresponding matches and their quality indices. In order to search for a composition match the user has to provide the version of the workspace in which ASS should search.

#UsrMgm
---++ User management
User Management component handles user registration, rights management, user authentication and group management.

It provides the following operation on users and groups:
   * =authenticateUser= checks the given user credentials
   * =registerUser= registers a user with the provided user data
   * =createGroup= creates a group using the provided group data
   * =modifyGroup= adds or removes users from a certain group
   * =modifyUser= updates the information about the user

#UsrInterface
---++ User interface
---+++ Compositor
---+++++!! Overview
The compositor contains the following elements:

<img src="%ATTACHURLPATH%/compositor.png" alt="Compositor elements" width='300' height='305'/>

---++++++!! Viewport
Shows part of the workspace and provide the following operations:
   * [[Team_C#PanP][pan]] moves to another part of the workspace
   * [[Team_C#ZoomP][zoom]] views a smaller or larger part of the workspace

---++++++!! Recommendation panel
For the current selected pieces/compositions lists all pieces and all compositions from all branches ordered by ASS match ranking. It provide the following operation:
   * search searches for a specific annotation

---++++++!! Other tools
Contains operations that eases composition management in the workspace:
   * [[Team_C#SelectP][select]] pieces/compositions
   * [[Team_C#UnSelectP][unselect]] pieces/compositions
   * [[Team_C#CutP][cut]] pieces/compositions
   * [[Team_C#PasteP][paste]] pieces/compositions

---+++++!! Operations
(Main article [[Team_C][formal specification user interface]])

The following operations can be performed in the compositor to modify the workspace:
   * [[Team_C#AddP][add]]
      * adds a piece or composition to the workspace
      * to add a single piece, a one-element composition is created
   * [[Team_C#RemoveComposition][remove composition]] removes a composition, including all its members, from the workspace
   * [[Team_C#RemoveMember][remove member]] removes a member from a composition and from the workspace
   * [[Team_C#ExtractP][extract]] removes a piece from a composition and re-adds it to the workspace in a new composition
   * [[Team_C#CombineP][combine]] 
      * takes the members of two compositions and creates a new composition with those members
      * removes the old compositions
   * [[Team_C#RotateP][rotate]] rotate a member or a composition around its center by the given angle
   * [[Team_C#TranslateP][translates]] translate (move) a member or composition to the given point
   * [[Team_C#AnnoteP][annotate]] add a annotation to a composition

---+++ Navigation manager
The Navigation Manager is responsible for the transitions between the screens of the system. The following diagram present how this transitions are made.

We assume that the following transitions are implicit
   * from each screen you can logout (back to !LogIn)
   * from each screen you can go back to home screen only if you are still logged in

<img src="%ATTACHURLPATH%/screen_diagram.png" alt="Screen diagram" width='480' height='360'/>

A user is allowed to do actions from a certain component only if the user's current screen equals the screen associated to the component.

| *Component* | *Screen* |
| Compositor | Compositor Screen |
| Communication | Discussion Screen | 
| User management | User management Screen |
| Piece management | Piece management Screen |

#CommSys
---++ Communication system
The Communication somponent has to provide the following  communication services: 
   * Direct public communication between multiple users. The users need to be online and logged in to be able to use the realtime communication service. The messages need not be accessible at later dates.
   * Indirect private communication between 2 users. A user(sender) sends a message to another user (recipient) in a mail like manner. This message is private to the two users. No other user should be able to access it. The recipient need not be online to receive the messages, he can access his messages after logging in.
   * Indirect public communication between multiple users in a forum. A user can post a message on a specific topic and other users can comment on this. The messages are stored within the system and are accessible at later dates. A moderator is able to delete topics or comments and close topics for further discussion. 

The Communication component accesses the User Management interface for user authentication and to be able to identify moderators.

---+ Reactive system
---++ Approach
We describe the behaviour of the system by means of a state machine. The following components are specified as state machines:
   * Compositor
   * Versioning system
   * Navigation manger
   * Communication system
   * User management

We assume that the input and output actions of all the components are distinct.
 
---++ State modeling
---+++++ !!System state 
The system state, _SysState_, is the combination between the global state and all the local states of the users.

%$\mathcal{U}$% = the set of users%BR%
%$\mathcal{LS}$% = the set of all possible local states%BR%
%$\mathcal{GS}$% = the set of all possible global states%BR%


%$SysState = (localState,\,G)$%
   * %$localState :: \mathcal{U} \rightarrow \mathcal{LS}$% (takes a user and returns the corresponding local state)
   * %$G\in\mathcal{GS}$%

---+++++ !!Local state 
A local state is specific to a certain user. It contains data that are accessible and modifiable only by its owner.

The local state for a user contains the following:
   * navigation state (current screen)
   * compositor state
      * %$\mathcal{W}$% = the set of compositions from the workspace
      * %$\mathcal{R}$% = the set of all current suggestions as given by the recommendation panel
         * %$\mathcal{R}=(\mathcal{R}_p,\mathcal{R}_c)$% = (pieces recommendations, compositions recommendations)
   * local communication state (instant messaging)

---+++++ !!Global state 
The global state is the same for all users. It can be accessed and modified by any user (with respect to the user rights).

The global sate contains the following:
   * versioning system state
      * %$\mathcal{B}$% = the set of all branches
   * communication component state (forum, mail system)
   * piece management state
   * user management state

---++ Transitions
---+++ Compositor
%BEGINLATEX%
\begin{tabular}{p{3cm}cp{5.1cm}}
	Pre & Action & Post \\
	\hline
	%add
	$\mathcal{W}, \mathcal{R}=(\mathcal{R}_p,\mathcal{R}_c)$
		& add(p,pos)
		& $\mathcal{W}\cup\{c\} ,\mathcal{R}$
	\\
	 & $ p \in \mathcal{R}_p$ & $c = (Seq_0\ Annotation, (p, pos, 0))$
	\\
	\\
	$\mathcal{W} , \mathcal{R}=(\mathcal{R}_p,\mathcal{R}_c)$
		& add(c,pos)
		& $\mathcal{W}\cup\{c'\}, \mathcal{R}$ \\
	 & $c = (a, s) \in \mathcal{R}_c$ & $c'=(a, Translate(s,pos))$ 
	 \\ \\
	 $\mathcal{W}\cup\,\{c\},\,\mathcal{R}$
		& remove(c)
		& $\mathcal{W},\,\mathcal{R}$\\
	\\
	$\mathcal{W}\cup\,\{c\},\,\mathcal{R}$
		& remove(m)
		& $\mathcal{W}\cup\{c'\},\,\mathcal{R}$ \\
	$c = (a, s)$ & $m \in s$ & $c' = (a, s-\{m\})$ 
	
	\\ \\
	
	$\mathcal{W}\cup\,\{c\},\,\mathcal{R}$
		& extract(m)
		& $\mathcal{W}\cup\{c',c''\},\,\mathcal{R}$\\
	 & $m \in c$ & $c' = c-\{m\}$\\
	 & & $c''= \{m\}$\\
	\\
	$\mathcal{W}\cup\,\{c_1,c_2\},\,\mathcal{R}$
		& combine($c_1$,$c_2$)
		& $\mathcal{W}\cup\{c\} ,\mathcal{R}$\\
	$c_1 = (a_1, s_1)$ & & $c = (a_1 \text{++} a_2, s_1 \cup s_2$)\\
	$c_2 = (a_2, s_2)$ & & 
	
	\\ \\
	
	$\mathcal{W}\cup\,\{c\},\,\mathcal{R}$
		& rotate($c$,$\theta$)
		& $\mathcal{W}\cup\{c'\},\,\mathcal{R}$\\
	 & & $c' = Rotate(c,\theta)$
	\\
	\\
	$\mathcal{W}\cup\,\{c\},\,\mathcal{R}$
		& translate($c$,$pos$)
		& $\mathcal{W}\cup\{c'\},\,\mathcal{R}$\\
	 & & $c' = Translate(c,pos)$
	 
	 \\ \\
	 
	 $\mathcal{W} \cup \{c\},\,\mathcal{R}$
		& annotate(c, a')
		& $\mathcal{W} \cup \{c'\},\,\mathcal{R}$ \\
	$c = (a, m)$ & & $c' = (\text{addAnn}\ a\ a', m)$
\end{tabular}
%ENDLATEX%
Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
png	compositor.png	manage	23.1 K	24 Oct 2009 - 11:42	CalinJuravle	Compositor elements
png	screen_diagram.png	manage	13.9 K	24 Oct 2009 - 12:54	CalinJuravle	Screen Diagram