Getting Started
==================================

Now that PiAnoS is installed, you want to create an exercise (i.e. upload images), a regular user and start playing. This small tutorial will help you get started.


Preparing the images
-----------------------------------

An exercise (or case) consists of two images: the mark (latent print) and the print (reference print). Since PiAnoS requires the resolution of the images, you need to make sure the meta-data is set appropriately (JPEG and TIFF formats typically contain this information). Further, the user's browser must be able to display the images, so their format must also be "browser-friendly" (this includes JPEG and PNG formats). There are advanced options to provide/override the resolution (e.g. in a meta-dataless PNG file) and convert TIFFs to PNGs on the fly so users can see them without trouble (browsers do not like TIFFs), but we'll stick to JPEG for the moment.

The ideal resolutions for images in PiAnoS are 1000dpi and 1200dpi. Lower/higher resolutions (e.g. 500dpi/2000dpi) can be used but the various annotations may look too big/small. Use your favorite image editing tool to convert your images to the JPEG format at the appropriate resolution.

You should now have at hand **two JPEG images at the same resolution** - this resolution can be 1000 or 1200 dpi.


The administration interface
------------------------------------

When logged in as a tutor (i.e. administrator), you are offered options that are not available to regular users. You are able to:

	- create and edit folders (groups of exercises)
	- create and edit exercises
	- create and edit groups of users
	- create and edit users

Most of these actions are initiated using the tree on the left-hand side of the screen. Selecting an item (e.g. folder, exercise) with the left mouse button shows detailed information in the main view. Right-clicking an item reveals a menu to perform operations related to this item (e.g. create an exercise when right-clicking a folder).

.. note:: Users of single button mice (Mac users, this is for you) should hold the `Ctrl` key while clicking to emulate the right click. Some mice and touchpads also allow the "dual finger tap" to act as a right-click.


Creating a folder and an exercise
------------------------------------

Folders are containers for exercises, typically used for a training session, a course, a workshop, etc.

	- Right-click "All exercises", and choose "Create new folder"
	- Give the folder a name, e.g. "Fingerprints 101"
	- Select the newly created "Fingerprints 101" folder. It's empty.
	- Either:
	  
	  * Right-click "Fingerprints 101" in the tree and select "Create new exercise"
	  * or click the "Create exercise here" button in the main view
	  
	- This shows the "new exercise" panel. Enter a name (e.g. "Case 1") and a meaningful description (e.g. "Trace revealed with powder on metal. Lifted using gelatin, inverted photograph")
	- For both the mark and the print:
	
	  * Click "Upload a new image"
	  * Browse for the image and click OK
	  * If everything went well, a preview will be shown in the box
	 
	- Validate with the "Create button"
	
	
Creating a group and a user
-------------------------------------

Users log into PiAnoS using a username and a password - they do not care which group they belong to. But for administration purposes, users are grouped, typically by membership in an organisation, by level, etc.

	- Right-click "All users", and choose "Create new group"
	- Give the group a name, e.g. "Spring 2013 Students"
	- Right-click the newly created group in the tree, and choose "Create new user"
	- In the dialog box, fill-in the information:
	
	  * Username: must be unique across all users. Users log-in with this name.
	  * Display name: the name as it is displayed everywhere in PiAnoS (the actual username will never show up)
	  * Password: please make it strong. Passwords can never be recovered in PiAnoS (they are hashed and the system does not know the actual passwords). Keep them in a `safe` place if you need to.
	  
	- Validate with "OK"
	
.. note:: The password policy is something you have to manage by yourself, and extreme care should be taken if your PiAnoS instance is facing the Internet. Leak of sensible information, loss of data, nuclear disaster, etc. are all possible if you choose usernames/passwords that are easy to guess, such as "user", "password".


Granting access to the exercise
-------------------------------------

Access rights are managed on a folder ``<->`` group(s) basis. That is, you grant access to a folder to one or several user groups. By default, a folder is not accessible to anyone. When access is granted to a group, all users of this group can see the exercise.

	- Select the "Fingerprints 101" folder
	- Click the "Change access rights" button, located in the "General information" pane
	- Click the "Spring 2013 Students" group in the list - this will highlight it
	- Validate with "OK"
	
	
Testing
---------------------------------------

It is always good to test if you set up everything correctly before users try to connect.

	- Log out of the administrator account by clicking the "Logout" link in the upper-right corner
	- Log in as the user you have just created
	- The folder and exercise you have created earlier should be visible in the tree. If they are not, go back to the previous steps and double-check everything
	- In the tree, select the exercise "Case 1"
	- Click the "Start this exercise button"
	- This brings you to the PiAnoS frontend, where you can actually work on the images, following the :doc:`../user/index`. This test makes sure PiAnoS works as expected, so that users are able to go through the complete examination process.
	
	  * Place some quality zones and a few minutiae
	  * Hit the "Save" button
	  * Expand the conclusion, and answer the questions
	  * Hit the "Submit" button to proceed to the comparison step
	  * Annotate the print, pair some minutiae, answer the questions and submit your work
	  
	- Click the "PiAnoS" link (or click your browser's "Back" button)
	- Log out of the user's account
	- Log in as administrator again, and select the exercise "Case 1"
	- The results you have submitted earlier are shown. At this point you can:
	
	  * Click the "Review" button to enter the review mode (only available to tutors, shows all results together)
	  * Click the red cross in the user's results row to delete your test submission
	  