# ibisa - Image-Based Identification/Search for Archaeology
# Copyright (C) 2008, 2009 Anthony Beurive'

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
#----------------------------------------------------------------------

namespace eval ::ibisa {
    ::map::array:variable help:tag:to:action

    # Returns the result of removing any whitespace from the given text.
    proc myTrim {text} {
        set prefix ""
        foreach word [split $text] {
            if {$word == {}} continue
            append prefix "$word "
        }
        return $prefix
    }

    # Help frame.
    help:tag:to:action:set help:frame {
        $text insert end "Welcome to IBISA!" gold

        set p [myTrim {This is IBISA's help frame.  It gives
            information about the interface components under the mouse
            pointer when such information is available.}]

        $text insert end "\n$p" normal

        #set p [myTrim {IBISA (Image-Based Identification / Search for
        #    Archaeology) is a scientific computer program.  Its
        #    purpose is to manage photos of archaeological items.
        #    Individual items can be extracted from photos showing
        #    collections of items.  They can then be compared together
        #    to find similarities.}]

        #$text insert end "\n$p" normal

        set p [myTrim {Shortcuts: F1 (show / hide), F2 / F3 (scroll up
            / down), F4 (freeze / unfreeze contents).}]

        $text insert end "\n$p" normal

        set p [myTrim {The frame can also be dragged and dropped with
            the mouse.  The first click should be on one of the sides.}]

        $text insert end "\n$p" normal
    }

    # Toolbar.
    help:tag:to:action:set toolbar {
        $text insert end "Toolbar" gold

        set p [myTrim {The toolbar contains a set of buttons to do
            various operations.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: F5 (show / hide).}]

        $text insert end "\n$p" normal
    }

    # Status bar.
    help:tag:to:action:set status:bar {
        $text insert end "Status Bar" gold

        set p [myTrim {The status bar displays messages when events
            occur.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: F6 (show / hide).}]

        $text insert end "\n$p" normal
    }

    # Cancel.
    help:tag:to:action:set operation:cancel {
        $text insert end "Cancel" gold

        set p [myTrim {Push this button to indicate that the current
            operation should stop as soon as possible.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Escape.}]

        $text insert end "\n$p" normal
    }

    # Import photos.
    help:tag:to:action:set collection:import {
        $text insert end "Import New Photos" gold

        set p [myTrim {IBISA works with a collection of photos.  At
            the beginning the collection is empty.  You should first
            import photos from your folders into the collection.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Control + i.}]

        $text insert end "\n$p" normal

        set p [myTrim {When you later import photos again the software
            will verify that they are not already in your collection
            and will only consider the new ones.}]

        $text insert end "\n$p" normal

        set p [myTrim {Use the "Collection" menu to change the current
            collection or to create new photo collections.  You can
            also clear the current collection, but be warned that this
            is not reversible.  However, the software never deletes
            original photos from disk, so you will be able to
            re-create a lost collection from scratch most of the
            time if you need so.}]

        $text insert end "\n$p" normal

        set p [myTrim {If you removed a photo from your collection
            (using the 'Delete' key) it won't appear again when you
            try to import new photos because it has been associated
            with the 'visited' flag.  If you really need to import it
            again you can use the "Collection" menu to clear all the
            'visited' flags.}]

        $text insert end "\n$p" normal
    }

    # Search.
    help:tag:to:action:set collection:search {
        $text insert end "Search The Collection" gold

        set p [myTrim {As your collection becomes bigger and bigger
            you may need a way to retrieve photos based on some
            criteria.  The search tool allows you to select photos
            which tags match a set of keywords.  If you have
            appropriately tagged your photos it might prove handy.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Control + k.}]

        $text insert end "\n$p" normal

        set p [myTrim {After you have typed the keywords hit 'Return'
            and the search will start.  Hit 'Escape' to cancel the
            search.}]

        $text insert end "\n$p" normal

        set p [myTrim {The special keyword 'all' can be used to go
            back to the whole set of photos.}]

        $text insert end "\n$p" normal
    }

    # Thumbnail.
    help:tag:to:action:set thumbnails {
        $text insert end "Thumbnails" gold

        set p [myTrim {These thumbnails are photos from your
            collection.  You can use the direction keys to navigate
            among them.  You will have a closer view by clicking on
            one of them or by hitting the 'Return' / 'Enter' key.}]

        $text insert end "\n$p" normal

        set p [myTrim {If you want to remove the currently selected
            photo from your collection use the 'Delete' key.  The
            corresponding file will *not* be deleted from disk but you
            won't be able to import it again because it has been
            flagged as 'visited'.  If you really need to import it
            again in the current collection use the "Collection" menu
            to clear all the 'visited' flags.}]

        $text insert end "\n$p" normal
    }

    # Home.
    help:tag:to:action:set home {
        $text insert end "Home" gold

        set p [myTrim {Go back to the thumbnails.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Alt + Home.}]

        $text insert end "\n$p" normal
    }

    # Back.
    help:tag:to:action:set context:back {
        $text insert end "Back" gold

        set p [myTrim {Go back one step in photo history, and finally
            to the thumbnails.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Alt + Left Arrow.}]

        $text insert end "\n$p" normal
    }

    # Forward.
    help:tag:to:action:set context:forward {
        $text insert end "Forward" gold

        set p [myTrim {Go forward in photo history.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Alt + Right Arrow.}]

        $text insert end "\n$p" normal
    }

    # Up.
    help:tag:to:action:set context:up {
        $text insert end "Previous Page" gold

        set p [myTrim {Push this button to display the previous page
            of thumbnails.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Page Up.}]

        $text insert end "\n$p" normal
    }

    # Down.
    help:tag:to:action:set context:down {
        $text insert end "Next Page" gold

        set p [myTrim {Push this button to display the next page of
            thumbnails.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Page Down.}]

        $text insert end "\n$p" normal
    }

    # Current photo.
    help:tag:to:action:set work:area:photo {
        $text insert end "Photo View" gold

        set p [myTrim {This is the photo you selected.}]

        $text insert end "\n$p" normal

        set p [myTrim {In zoom mode you can zoom to a specific part
            by selecting it with the mouse.  Single clicks will zoom
            back to the original view and finally to the thumbnails.}]

        $text insert end "\n$p" normal

        set p [myTrim {In outline mode you can outline specific
            regions of the current photo to later extract them as new
            photos.  Single clicks work the same in outline mode as in
            zoom mode.  The eraser mode allows you to delete parts of
            the outline if you are unhappy with it.}]

        $text insert end "\n$p" normal

        set p [myTrim {In tag mode you can attach tags to the current
            photo.  Some tags have been automatically given to each of
            your photos but you can change them, delete them or create
            new ones whenever you want.}]

        $text insert end "\n$p" normal

        set p [myTrim {Specific tools can be used to adjust the
            current view.  They can perform translation, rotation,
            scale and opacity changes.  Use F8 to toggle them on and
            off.}]

        $text insert end "\n$p" normal
    }

    # Photo tools.
    help:tag:to:action:set photo:tools {
        $text insert end "Photo Tools" gold

        set p [myTrim {Photo tools can be used to adjust the current
            view.  They can perform translation, rotation, scale and
            opacity changes.  Use F8 to toggle them on and off.}]

        $text insert end "\n$p" normal
    }

    # Translate photo tool.
    help:tag:to:action:set photo:tools:translate {
        $text insert end "Translate" gold

        set p [myTrim {To horizontally and vertically shift the
        current view of the photo.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Left / Right / Up / Down.}]

        $text insert end "\n$p" normal
    }

    # Rotate photo tool.
    help:tag:to:action:set photo:tools:rotate {
        $text insert end "Rotate" gold

        set p [myTrim {To rotate the current view of the photo.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Shift + Left / Right.}]

        $text insert end "\n$p" normal
    }

    # Scale photo tool.
    help:tag:to:action:set photo:tools:scale {
        $text insert end "Scale" gold

        set p [myTrim {To zoom in or out the photo.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Shift + Up / Down.}]

        $text insert end "\n$p" normal
    }

    # Opacity photo tool.
    help:tag:to:action:set photo:tools:opacity {
        $text insert end "Opacity" gold

        set p [myTrim {To change the opacity of the current view.
        This can be useful if a reference photo was chosen for the
        background.}]

        $text insert end "\n$p" normal
    }

    # Home photo tool.
    help:tag:to:action:set photo:tools:home {
        $text insert end "Reset" gold

        set p [myTrim {To view the whole photo again.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: Home.}]

        $text insert end "\n$p" normal
    }

    # Photo zoom mode.
    help:tag:to:action:set:foreach:key {photo:zoom:mode zoom:mode} {
        $text insert end "Zoom Mode" gold

        set p [myTrim {Zoom to a specific part of the current photo by
            selecting it with the mouse.  Single clicks will zoom back
            to the original view and finally to the thumbnails.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcut: 'z'.}]
        $text insert end "\n$p" normal
    }

    # Photo outline mode.
    help:tag:to:action:set:foreach:key {photo:outline:mode outline:mode} {
        $text insert end "Outline Mode" gold

        set p [myTrim {You can outline a region of the current photo
            by drawing it with the mouse.  You will later be able to
            extract the region as a new photo in your collection and
            specifically work on it.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcuts: 's' for segment drawing mode, 'e'
            for eraser mode.  While drawing, hold 'Control' for
            straight lines.  Use 'Delete' to remove all lines.}]

        $text insert end "\n$p" normal

        set p [myTrim {You can draw line segments separately and later
            connect them together.  To extend an existing segment,
            start drag & drop close to one of its extremities.
            Likewise, to connect to another segment, finish drag &
            drop close to one of its extremities.  If you are still
            unhappy with the result you can use the eraser to delete
            the wrong parts.}]

        $text insert end "\n$p" normal

        set p [myTrim {Note that it is always possible to switch back
            and forth between zoom and segment modes to outline a
            region with the most appropriate precision.}]

        $text insert end "\n$p" normal
    }

    # Photo eraser mode.
    help:tag:to:action:set:foreach:key {photo:eraser:mode eraser:mode} {
        $text insert end "Eraser Mode" gold

        set p [myTrim {If you are unhappy with some parts of the
            current outline you can use the eraser to delete them.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcuts: 'e' for eraser mode, 's' for segment
            drawing mode.  Use 'Delete' to remove all lines.}]

        $text insert end "\n$p" normal
    }

    # Object extraction.
    help:tag:to:action:set photo:outline:extract {
        $text insert end "Extract Region" gold

        set p [myTrim {When you have outlined a region in the current
            photo, you can make it a new object in your collection.
            The region will be copied into a new photo on which you
            will be able to specifically work.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcuts: Shift + X.}]

        $text insert end "\n$p" normal

        set p [myTrim {There are interesting features about extracted
            regions: they are given a copy of all the tags of their
            parents.  They are also given a tag to indicate that they
            are indeed extracted regions (or objects).  You can use
            these features to later search for regions.}]

        $text insert end "\n$p" normal

        set p [myTrim {The extracted region corresponds to the closed
            lines (i.e., polygons) that you have drawn in the outline
            mode.  Open lines will not be considered.}]

        $text insert end "\n$p" normal

        set p [myTrim {Simply speaking, if there is just one polygon
        then the extracted region will be the part inside the polygon.
        However, if there are more polygons then they will all
        contribute to the extracted region depending on their relative
        positions.  For instance, if a polygon is inside another
        polygon it will result in a hole in the extracted region.}]

        $text insert end "\n$p" normal
    }

    # Photo tag mode.
    help:tag:to:action:set:foreach:key {photo:tag:mode tag:mode} {
        $text insert end "Tag Mode" gold

        set p [myTrim {In the tag mode you can attach tags to the
            current photo.  Just click and drag on a part of the photo
            and enter the text of the tag.  Hit 'Escape' when you are
            done.  Click on an existing tag to change it.  Use drag
            and drop to move it.}]

        $text insert end "\n$p" normal

        set p [myTrim {Shortcuts: 't' for tag mode.}]

        $text insert end "\n$p" normal

        set p [myTrim {Empty tags will be automatically deleted.  To
            delete a specific tag you can also move the mouse pointer
            over it and hit 'Delete'.  (Hit 'Escape' first if it has
            the focus.)  If you hit 'Delete' outside of tags you will
            be proposed to delete all of them if you wish so.}]

        $text insert end "\n$p" normal

        set p [myTrim {There are interesting features about extracted
            regions: they are given a copy of all the tags of their
            parents.  They are also given a tag to indicate that they
            are indeed extracted regions (or objects).  You can use
            these features to later search for extracted objects.}]

        $text insert end "\n$p" normal
    }

    # Set photo reference.
    help:tag:to:action:set set:photo:reference {
        $text insert end "Set Photo Reference" gold

        set p [myTrim {You can set the current photo as the reference.
        Other photos can be compared to the reference in order to find
        similarities.}]

        $text insert end "\n$p" normal

        set p [myTrim {When the photo reference is set it will show up
        in the background of the current photo view.  By changing the
        opacity of the current view you will be able to compare it
        with the reference.}]

        $text insert end "\n$p" normal

        set p [myTrim {Using your own eyes for this task is not easy.
        Algorithms have been written to see how much computers can
        help on that matter.  Please refer to the registration
        operations.}]

        $text insert end "\n$p" normal
    }

    # Unset photo reference.
    help:tag:to:action:set unset:photo:reference {
        $text insert end "Unset Photo Reference" gold

        set p [myTrim {Use this operation to clear the photo
        reference.  It won't show up anymore in the background of
        photo views.}]

        $text insert end "\n$p" normal
    }

    # Intercorrelation.
    help:tag:to:action:set intercorrelation {
        $text insert end "Intercorrelation" gold

        set p [myTrim {This operation computes the intercorrelation
        between the current photo and the reference photo.  The result
        ranges from 0 to 1.  It is 1 when the two photos are strictly
        identical.}]

        $text insert end "\n$p" normal
    }

    # Photo registration.
    help:tag:to:action:set photo:registration {
        $text insert end "Photo Registration" gold

        set p [myTrim {This operation registers the selected photo
        with the reference photo.}]

        $text insert end "\n$p" normal

        set p [myTrim {The results are affine transformation
        parameters and an intercorrelation value (from 0 = no
        similarity, to 1 = strictly identical) that can later be used
        to display photos in decreasing similarity.}]

        $text insert end "\n$p" normal
    }

    # Group registration.
    help:tag:to:action:set group:registration {
        $text insert end "Group Registration" gold

        set p [myTrim {This operation registers the current photo with
        the other photos, and displays them in decreasing
        similarity.}]

        $text insert end "\n$p" normal

        set p [myTrim {For each pair of photos, the results of
        registration are affine transformation parameters and an
        intercorrelation value (from 0 = no similarity, to 1 =
        strictly identical).}]

        $text insert end "\n$p" normal
    }

    # Show photo neighbors.
    help:tag:to:action:set show:neighbors {
        $text insert end "Show Neighbors" gold

        set p [myTrim {Displays the neighbors of the current photo, in
        decreasing similarity.}]

        $text insert end "\n$p" normal

        set p [myTrim {Photo neighbors are built by triggering photo
        registrations, resulting in affine transformation parameters
        and intercorrelation values.  If such registrations were not
        previously triggered, the current photo has no registered
        neighbors in the collection.}]

        $text insert end "\n$p" normal
    }

    # Clear photo neighbors.
    help:tag:to:action:set clear:photo:neighbors {
        $text insert end "Clear Photo Neighbors" gold

        set p [myTrim {Clears the results of previous registrations
        involving the current photo.}]

        $text insert end "\n$p" normal
    }

    # Clear all neighbors.
    help:tag:to:action:set clear:all:neighbors! {
        $text insert end "Clear All Neighbors" gold

        set p [myTrim {Clears the results of all previous
        registrations, for all photos in your collection.}]

        $text insert end "\n$p" normal
    }

}

