detailed KDE Nepomuk Manual

Howto: Manage your file collection using KDE 4.7 and the Nepomuk-Framework

(2014-01-19)
As an addition to this article, there is an update now about the changes since KDE 4.7, using KDE 4.11 as reference version:
https://kdenepomukmanual.wordpress.com/2014/01/16/nepomuk-manual-update-kde-4-11-2/

Because I wasn’t able to find a complete KDE-Nepomuk documentation or howto, where everything important for the user is covered (from the installation to the search queries, with all the caveats), I decided to write one myself. It is intended for understanding and using Nepomuk, in combination with Dolphin, digiKam, Gwenview and Krunner, but no development topic is covered. It is also far from complete, so any information (about mistakes, additional topics,…) is HIGHLY APPRECIATED 🙂

You can download a PDF version of this manual here:
http://pdfcast.org/download/kde-nepomuk-semantic-desktop-user-s-manual.pdf

Note (2012-03-10):
KDE shipped version 4.8.1, containing performance improvements and bugfixes for Nepomuk and applications using Nepomuk. So everyone who experienced problems should give it a try.
http://www.kde.org/announcements/announce-4.8.1.php

Content of the KDE Nepomuk Howto :
1) What is Nepomuk and Nepomuk-KDE?
1.1) Why should someone use Nepomuk?
1.2) What is Nepomuk?
2) Setting up Nepomuk for KDE 4.7
3) Using Nepomuk
3.1) Dolphin
3.2) digiKam
3.3) Gwenview
3.4) Krunner

1) What is Nepomuk and Nepomuk-KDE?

1.1) Why should someone use Nepomuk?

Usually, data on the hard disk is organised by their file names and directory structure. The common way to open a file is to change into its directory and open it by filename, if the filename and its directory is known. Otherwise, a filename or file content search is performed to locate the file. To look at its content, usually it has to be opened.

Nepomuk uses this common ways too, but extends it with more ways to describe a file, so it is easier to locate it and to get more information than just the filename from it.

So Nepomuk is for you if you:

– Think that organising your files only with subdirectories and filenames is not informative and efficient enough.

– Have large collections of pictures and/or music and you want to perform searches among them.

– Have large collections of pictures and/or music and you want to get information of the files without opening it (i.e. who is on a picture, which one was good etc.).

– Keep different versions of the same file or folder on your hard drive and you want to have information available which specifies them.

– Work with more files distributed in different folders over your hard drive and you don’t want to have so many file manager tabs opened.

– Want to perform indexed searches for file contents over all files on your hard drive.

– Download lots of files from the internet where you need to remember the download-URL (i.e. for citations in scientific papers)

– Want to store more information to files you downloaded.

– Have large documents or papers where you want to rate them and remember the important parts.

Nepomuk is not for you if you:

– Feel completely satisfied organising your hard drive by files and folders

– Work frequently on different computers and operating systems (because the KDE Nepomuk database is not transferrable to Microsoft Windows)

1.2) What is Nepomuk?

Nepomuk stands for“Networked Environment for Personal, Ontology-based Management of Unified Knowledge” and is the specification of a semantic desktop. KDE implemented it in Nepomuk-KDE.

Semantic Desktop…to me it sounded more like something that I want to keep as far away aspossible from my desktop. But I gave it a try, and really, it’s not that bad. Although there is no strict specification what a semantic desktop should be like, there is one main feature: Assigning meta-data to any kind of file. You probably know this from the ID3-tags of mp3 files, where information like artist, album, year and some tags can be stored independently of the filename. Now imagine to be able to do this to any kind of file, be it a text-file, video-file, or whatever. And to be able to search for them afterwards using the meta-data and content.

With the Nepomuk semantic desktop enabled, you will be able to do the following kind of things:

– Assign tags to files

– Assign arbitrary comments to files

– Give ratings to files

– Indexed search in the whole file system for file names

– Indexed search in the whole file system for file contents

– Indexed search for file types and modification dates

– Indexed search for tags

– Create virtual folders (folders where all files matching certain search criteria are shown, i.e. a certain tag or rating)

Unlike mp3-files, the meta-data is not stored in a file itself, but in a central database in KDE. In order to be able to view it on another computer, you have to transfer it.

The Nepomuk framework consists of several parts that implement the functionality:

Nepomuk is the framework itself, that provides the functionality implemented in several programs, like rating your files etc. Requests are passed to soprano, which is a library for reading and writing RDF data (resource description framework, designed by the W3C for storing metadata of files, exactly what we need here). The data itself is stored in a virtuoso database. And how do we get the data? This is Strigi’s task, a file indexer that scans for metadata in the filesystem.

2) Setting up Nepomuk for KDE 4.7

The semantic desktop inKDE 4.7 works basically out of the box, there are only a few clicks to do.
First of all, you have to install all the required elements that are needed with the package manager.

So start YaST2 or any other package manager and make sure to install the following packages:

– nepomukcontroller

– strigi

– libstrigi0

– kdegraphics-strigi-analyzer

– libsoprano4

– soprano

– soprano-backend-redland

– soprano-backend-virtuoso

– virtuoso-drivers

– virtuoso-server

The next step is to activate the nepomuk-services and make KDE applications nepomuk-”aware”. Go into the Service Manager (simply enter “service manager” in the KDE menu search bar) and make sure the startup-service “Nepomuk Search Module” is up and running.
Next, open the desktop search configuration (enter “desktop search” in the KDE menu search bar).

Make sure that the options “Enable Nepomuk Semantic Desktop” and “Enable Strigi Desktop File Indexer” are checked.

Now go into the tab “Desktop Query”.

Here you can customise the files and folders that you want Strigi to index. The option “Customize index folder…” opens the selection dialog.

The exclude filters are good as they are, but in the “Strigi Index Folders” you have to choose yourself which files should be in your index. This depends on which files you want to find quickly using tags and keywords. It’s recommended for folders inside your home directory, for example pictures, music, cumulated download folders (because of the little informative file names), educational scripts (you can view what it is about without opening it), and everything where the natural structure through the file system comes to its limits.

It’s not recommended for all the other system folders (bin, boot, dev,…) programming (too much text and therefore long indexing times), their version management systems (like SVN), ebook-folders (too much text too).

Because of the fact that the indexing database grows quickly, you really should only index your personal files and collections, where you are in need of better structure. For finding system files or grabbing their content, it’s better (and much faster) to use the traditional locate-tool on the command line and non-indexed search tools like find, grep or the KDE find utility Kfind.

So now that Nepomuk is set up, it will start the initial file indexing (if it doesn’t, try a reboot). It’s indicated with the Nepomuk file indexing icon  in the task bar. Right-clicking this icon lets you choose the options mentioned before.

Depending on how many files are in your chosen directories, the initial indexing can take a while. It only takes this long at the first time, but this reveals a big disadvantage of the Nepomuk semantic desktop: A fast index checking has to be performed at every startup of KDE, even if there were no modifications, because it is not possible to determine whether there was a modification between the two restarts or not. So Strigi has to scan the whole filesystem at every startup, which takes about 20 minutes and has low CPU priority, so it shouldn’t affect your work too much, and you can suspend it at any time (by right-clicking on the file indexing iconand choosing “Suspend File Indexing”).

Now Nepomuk is set up and ready to use, so let’s assign some meta-data.

3) Using Nepomuk

3.1) Dolphin

There are some documentations on the internet that state that search queries can be executed using the search field in Dolphin, but in KDE 4.7 the search bar in Dolphin doesn’t exist any more. Instead, there are two buttons in Dolphin that are important for Nepomuk: Search and Find.

The Find-button opens the search bar for indexed file and content search, the Search-button shows the sidebar where you can search for filetypes, change dates, ratings and tags. The indexed search and the metadata-search can even be combined.

If you don’t see the Search and Find buttons, you can add them using “configure toolbars”, either right-click somewhere in the free space right beside the buttons, or show the Dolphin-Menu with Ctrl+M and click on settings-> configure toolbars.

The indexed search can be used even without having assigned metadata to a file, like rating or tagging. Simply enter a search term into the search bar and choose if only file names or the whole file content should match, and if you want to search only in the current directory or everywhere.

Note that as soon as you enter the first character in the search bar, the indexed search begins and lists every file matching the search criteria. This list is updated continuously while you write, so emptying the search bar by deleting all characters lists the whole file index – this cantake a while.

There are some simple rules for performing search queries:

– Search terms can contain blanks, so even whole sentences are possible

– The asterisk “*” is the wildcard, you only need it for for parts inside a word. (i.e. “th*y” matches “theory”). At the end and the beginning of a search term there is always a wildcard.

– The index is built on keywords, this means the blank is the natural separator. In order to search for a whole word, you just need to enter it, without any wildcards.

– To search for a middle part, just enter the middle part, the wildcards are added automatically.
(i.e. searching for *eor* or eor matches for example with teori, theory, theorie, musictheory,…)

– Matches of the search query in the absolute path of the files as well as in the tags are also listed.

Unicode Bug:

Virtuoso 6.1.3 suffered from a unicode bug. The Unicode bug caused wrong indexing of special characters (ä, ö, ü, å, é,…) so that they appeared in search queries even if they didn’t match. You can test if you have wrong index files: Go to the filename-search, and enter a short search term with two wildcards (i.e. *eor*). If wrong results appear, and they have special characters in them, it’s due to the unicode-bug.

You can easily rescan the files:

In KDE <= 4.7:

Just open a terminal and enter (without any line breaks):

qdbus org.kde.nepomuk.services.nepomukstrigiservice /nepomukstrigiservice org.kde.nepomuk.Strigi.indexFolder /directory/ 1 1

Where /directory/ is the directory where the indexing should start (it walks recursively afterwards, you just need the upper directory where you want to start, i.e. your home directory)

In KDE 4.8:

Just open a terminal and enter (without any line breaks):

qdbus org.kde.nepomuk.services.nepomukfileindexer /nepomukfileindexer org.kde.nepomuk.FileIndexer.indexFolder /directory/ 1 1

Where /directory/ is the directory where the indexing should start (itwalks recursively afterwards, you just need the upper directory where you want to start, i.e. your home directory)

Further information about the Unicode bug:

https://bugs.kde.org/show_bug.cgi?id=271664

http://trueg.wordpress.com/2011/12/05/manually-forcing-the-re-indexing-of-folders-is-easy/

Searching via tags and rating:

Searching via tags and rating can either be done additionally to the keyword search or stand-alone. In order to search for them, they have to exist in the first place. To do this, click on any file you want and edit the parameters in the information area (on/off with F11). You can configure the amount of information shown there by right-clicking inthe empty area and choosing “configure”. There are 3 editable Elements:

– Comment (arbitrary text)

– Rating (choosing between 0 and 5 stars)

– Tags (choosing existing or creating new tags)

Any other information displayed can be used for a search query, as it will be mentioned later.

Comments:

To add a comment, click on the blue “Add Comment…”-text to open the comment editor window.

Now write your comment into the editor and hit “OK” or Alt+o.

The saved comment is displayed in the information field:

Rating:

Just click the desired amount of stars (you can also cut them in half) to rate your document:

Tags:

Clicking on the blue text“Add Tags…” lets you choose existing tags (if there are any) or creating new tags.

Some KDE Applications (like DigiKam) add tags themselves. You can create a new tag by simply writing its name in the text field. If the tag already exists,the old tag is used (so be careful with the writing to not have 2 tags in different spelling that were meant to be the same). Hitting OK saves the tags.

NOTE: Special characters, like ö, ü, ä, é, å,… weren’t displayed correctly in the add tags field and, even worse, couldn’t be deleted any more. So it’s best not to use them.

Now they are displayed in the information field, too:

Deleting a tag:

Open the add-tags window again and move the mouse to the right side of the white area besides the tag name. A red “X” appears to delete the tag.

The information entered in comments and tags is also used in the indexed search.

Editing metadata of more than one file at once:

BUG: To select more files and assign metadata to them all at once, you have to be carefully because of a bug in Dolphin. If you select more files (using Shift, Strg or the mouse), the information in the information panel on the right-hand side is not updated instantly, but with a delay of some seconds, especially in folders with many files, where all are selected with Strg+A. Editing the metadata too early causes a certain crash of Dolphin (but fortunately nothing worse happens). So you have to wait until the long list of metadata (which is usually shown when one file is selected) disappears and only the selection of comments, rating and tags appears, then it is safe to edit them.

To search the Nepomuk-database using the entered comments, ratings and tags you can use the information panel (to search for files with the same values, i.e. the creating date, just click on the value in the information panel, and all files with the same value are listed) or the search panel (F12 or clicking on Search-button). You can search for document types, modification dates, rating, and you can see your own tags at the bottom of the panel.

Simply clicking on an option invokes a search over the whole database for this value. Clicking on “more” opens the tag window, where you can search in your list of tags.

To combine indexed text search and metadata-search, click first on Find to invoke a query for a text, and then choose the options you want from the search panel.

Creating Virtual folders:

Normally, files are grouped in folders by location, that means, the folder view shows all the files that are located in this folder. The Nepomuk virtual folders groups files by search criteria, which means all the files matching certain search criteria are displayed in the virtual folder, independently of their real location on the hard disk. This can be useful if you need a couple of files from different folders frequently. Then there is no need to switch folders or copy files to another location all the time, because all of the files are shown in one virtual folder.

In order to create a virtual folder, perform an arbitrary search query, and make sure you have your places-panel displayed (F9). Then right-click in some free space in the file area and choose “Add toPlaces…”.

Label your new entry and and leave the location as it is. If you want to use that folder in other applications besides Dolphin, uncheck “Onlyshow when using this application (Dolphin)”. Then click OK. Your virtual folder is now in your places panel, a click on it performs a Nepomuk search and displays the results. That means, if new files are coming to match the search criteria in the future, they will be displayed automatically alongside the others. It a file loses the search criteria, it will disappear.

Clicking on “testfolder” lists all files with the tag “Birthday” in the file view as if it were a normal folder.

3.2) digiKam

Unlike Dolphin, digiKam can use a separate database for storing its metadata. The use of Nepomuk has to be activated manually in “Settings → Configure digiKam” and then in “Metadata →Nepomuk”. Make sure the options “Store metadata from digiKam in Nepomuk” and “Read metadata from Nepomuk” are activated. If you have already set some metadata in digiKam that you want to synchronise with Nepomuk, click on “Fully Resynchronize again”.

DigiKam is able to store lots of metadata for every picture, but not all of it is synchronised with Nepomuk, and only tags and ratings appear in other applications (like Dolphin). In order to manually tag a picture in digiKam, select it and click on “Caption/Tags” in the menu on the right hand side of digiKam.

Click on “Tags” to see and choose tags from you list of tags. To create a new tag, right-click on “My Tags” (or alternatively right-click on the picture itself and choose “Assign Tags → Add New Tag…”)

Now the tag editor opens. It lets you assign tags to a picture by writing them into the title field (separated by commas). To create hierarchical tags, use the slash “/”.

Hierarchical tags appear as a folder structure in digiKam to let you find them easier and avoid long lists of tags, in other applications they appear as single tags. For example, a tag tree with “Schweden” as a main tag and “Stockholm” and “Paintball” as sub-tags will appear as 3 different tags in Dolphin.

In the tag editor you can also assign shortcuts to tags, so different tags can be assigned to selected pictures via different shortcuts. Tags that already exist or that are already assigned will be left unchanged, all the others are assigned or created and assigned.

To browse your tagged pictures, click on “Tags” in the side menu at the left-hand side of digiKam. By clicking on a tag, all the pictures with this tag are shown, grouped by albums. Note that only pictures of digiKam-albums are shown, and not of the whole disk.

To rate a picture in digiKam, just hover the mouse pointer over it and chose an amount of stars, or click on it and select the rating in the “Description”-Tab of the “Caption/Tags” menu on the right-hand side of digiKam.

Tagging pictures in digiKam with face detection

DigiKam has a new feature to detect faces in pictures, which can be tagged afterwards (mostly with the name of the person shown). According to the GUI, there is an option to not only recognise faces, but also recognise the people shown. But at the moment (January 2012) the function isn’t implemented yet and just results in no tags. See

https://bugs.kde.org/show_bug.cgi?id=271679

for further information.

But the recognition of pictures with faces on it works very well and can make the organisation of large image collections much easier.

To start the face detection, click on “People” in the menu on the left-hand side of digiKam.

At the first time, there is no tags but only the button “Scan collection for faces”.
Clicking on it offers two possibilites:

– Detect and recognize faces

The chosen photos are scanned for the appearance of faces. The currently unimplemented functionality would also assign people-tags to them on the basis of other tagged photos where this face appears.

After the detection, all photos with faces on it are shown, or assigned with the tag “Unknown” which you can chose in the tag-area below the “Scan collection for faces”-button. You can either assign a tag directly in the text area below, if you are in the Thumbnails-view:

Just enter the name of the person in the picture and click on the blue confirmation icon. Don’t worry if there is more than one face on the picture, every photo is shown as often as the number of faces on it, and every time one person gets tagged.

For every new name, a tag is created in digiKam and Nepomuk (if synchronisation is activated).

If you want to tag the pictures in their actual size, click on “ViewImage” besides “Thumbnails”, that you can tag people by hovering the mouse pointer over them and choosing/creating a tag.

The second option

– Recognize faces

seems to be currently unimplemented. It would already assign the right tags on the pictures where the face is recognised, and tag the rest with“unknown”. At the moment, all are “unknown”.

3.3) Gwenview

In Gwenview, it is also possible to change ratings, tags and comments of pictures.

Jus tmake sure the sidebar is visible (F11).

Then select one picture, and click on the “Information” tab in the sidebar.

Here you can change the ratings, tags and comments.

3.4) Krunner

The Krunner application (Alt+F2) has Nepomuk-integration, too. Activate it with “Nepomuk Desktop Search Runner” in the settings to perform Nepomuk searches via entering keywords. In my opinion, it is much less comfortable than searching via Dolphin, and needs much scrolling in case of long lists.

Tags: comment, desktop, digikam, gwenview, kde, krunner, linux, nepomuk, rating, semantic, strigi, tag, virtuoso