Gramps - User contributions [en]

Addon:Photo Tagging Gramplet

2013-11-03T20:14:24Z

Aglebov: Wrote a portion of the manual

[[Image:Photo-Tagging-Screenshot.jpg|500px|thumb|right|The gramplet window consists of the toolbar, the selection area (center-left) and the list of tagged people (center-right).]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Selection area ===

The selection area displays the image and highlights the regions that have been associated with person in the Gramps database.

The mouse wheel can be used to zoom in and out of the image. Alternatively, you can use the corresponding toolbar buttons.

Left click inside of one the regions makes this region active. Right-click causes the context menu to be displayed.

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected region. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, first make it active by clicking inside the region. Move the mouse pointer to one of the borders or corners of the selection box. A grabbing handle will appear that you can drag to modify the shape of the box.

To change the person associated with the region, use the toolbar buttons or the context menu.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The gramplet toolbar (the exact appearance can depend on the operating system and the version of the GTK library used).]]

Use the toolbar to modify the associations of the current image.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== List of tagged people ===

The list contains the people tagged in the current image, as well as the selection boxes that have not yet been associated with a particular person. A thumbnail image of the corresponding region of the image is displayed in every row.

Left-click on a row in the list selects the corresponding region in the image. Further manipulations can be

Double-click on a row with a person opens the Gramps 'Person' dialog for this person. This is equivalent to pressing the 'Edit' button in the gramplet toolbar.

== To do ==
Some of the ideas to be implemented in future versions of the gramplet:
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T09:45:38Z

Aglebov: Edited the caption for the screenshot

[[Image:Photo-Tagging-Screenshot.jpg|500px|thumb|right|The gramplet window consists of the toolbar, the selection area (center-left) and the list of tagged people (center-right).]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Selection area ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The toolbar.]]

Each buttons carries a specific function.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== List of tagged people ===

The list contains the people tagged in the current image, as well as the selection boxes that have not yet been associated with a particular person.

Clicking on a row in the list selects the corresponding region in the image.

Double-clicking on a row with a person opens the Gramps 'Person' dialog for this person. This is equivalent to pressing the 'Edit' button in the gramplet toolbar.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T09:43:34Z

Aglebov: Moved the text from the Workflow subsection to the Selection Area subsection and removed the Workflow subsection

[[Image:Photo-Tagging-Screenshot.jpg|500px|thumb|right|The main window.]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Selection area ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The toolbar.]]

Each buttons carries a specific function.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== List of tagged people ===

The list contains the people tagged in the current image, as well as the selection boxes that have not yet been associated with a particular person.

Clicking on a row in the list selects the corresponding region in the image.

Double-clicking on a row with a person opens the Gramps 'Person' dialog for this person. This is equivalent to pressing the 'Edit' button in the gramplet toolbar.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T09:42:14Z

Aglebov: /* List of tagged people */ Filled the list of tagged people subsection

[[Image:Photo-Tagging-Screenshot.jpg|500px|thumb|right|The main window.]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Selection area ===

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The toolbar.]]

Each buttons carries a specific function.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== List of tagged people ===

The list contains the people tagged in the current image, as well as the selection boxes that have not yet been associated with a particular person.

Clicking on a row in the list selects the corresponding region in the image.

Double-clicking on a row with a person opens the Gramps 'Person' dialog for this person. This is equivalent to pressing the 'Edit' button in the gramplet toolbar.

=== Workflow ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T09:16:23Z

Aglebov: Added subsections for selection area and list of tagged people

[[Image:Photo-Tagging-Screenshot.jpg|500px|thumb|right|The main window.]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Selection area ===

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The toolbar.]]

Each buttons carries a specific function.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== List of tagged people ===

=== Workflow ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T09:14:44Z

Aglebov:

[[Image:Photo-Tagging-Screenshot.jpg|500px|thumb|right|The main window.]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The toolbar.]]

Each buttons carries a specific function.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== Workflow ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

File:Photo-Tagging-Screenshot.jpg

2013-10-16T09:12:17Z

Aglebov: Aglebov uploaded a new version of "File:Photo-Tagging-Screenshot.jpg"

Addon:Photo Tagging Gramplet

2013-10-16T09:02:39Z

Aglebov:

[[Image:Photo-Tagging-Screenshot.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The toolbar.]]

Each buttons carries a specific function.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== Workflow ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

File:Photo-Tagging-Screenshot.jpg

2013-10-16T09:02:12Z

Aglebov:

Addon:Photo Tagging Gramplet

2013-10-16T08:57:17Z

Aglebov: Added a screenshot

[[Image:Photo-Tagging-Screenshot.gif|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The toolbar.]]

Each buttons carries a specific function.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== Workflow ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

File:Photo-Tagging-Screenshot.gif

2013-10-16T08:56:36Z

Aglebov: Aglebov uploaded a new version of "File:Photo-Tagging-Screenshot.gif"

File:Photo-Tagging-Screenshot.gif

2013-10-16T08:54:44Z

Aglebov:

Addon:Photo Tagging Gramplet

2013-10-16T08:37:54Z

Aglebov:

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

The toolbar contains nine buttons that are made active in accordance with the current state of selection.

[[Image:toolbar.gif|The toolbar.]]

Each buttons carries a specific function.

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog. Once selection is made, the person is tagged in the current box.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== Workflow ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T08:33:57Z

Aglebov:

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

[[Image:toolbar.gif|The toolbar.]]

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog.

[[File:New.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== Workflow ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T08:33:12Z

Aglebov: /* Toolbar */ Added toolbar buttons with descriptions

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

[[Image:toolbar.gif|The toolbar.]]

[[File:Select.gif]] Displays the Gramps 'Select Person' dialog.

[[File:Add.gif]] Creates a new person and displays the Gramps 'Person' dialog.

[[File:Clear.gif]] Removes the tag from the current box.

[[File:Remove.gif]] Removes the current box together with the tag.

[[File:Edit.gif]] Displays the Gramps 'Person' dialog for the person tagged in the current box.

[[File:Zoomin.gif]] Zooms the image in.

[[File:Zoomout.gif]] Zooms the image out.

[[File:Detect.gif]] Runs the detection algorithm.

[[File:Settings.gif]] Displays the gramplet settings dialog.

=== Workflow ===

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

File:Photo-Tagging-Settings-icon.gif

2013-10-16T08:26:48Z

Aglebov:

File:Photo-Tagging-Detect-icon.gif

2013-10-16T08:26:39Z

Aglebov:

File:Photo-Tagging-Zoomout-icon.gif

2013-10-16T08:26:28Z

Aglebov:

File:Photo-Tagging-Zoomin-icon.gif

2013-10-16T08:26:18Z

Aglebov:

File:Photo-Tagging-Edit-icon.gif

2013-10-16T08:26:04Z

Aglebov:

File:Photo-Tagging-Remove-icon.gif

2013-10-16T08:25:50Z

Aglebov:

File:Photo-Tagging-Clear-icon.gif

2013-10-16T08:25:39Z

Aglebov:

File:Photo-Tagging-New-icon.gif

2013-10-16T08:25:24Z

Aglebov:

File:Photo-Tagging-Select-icon.gif

2013-10-16T08:25:09Z

Aglebov:

Addon:Photo Tagging Gramplet

2013-10-16T08:18:34Z

Aglebov: /* Toolbar */

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

[[Image:toolbar.gif|The toolbar.]]

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T08:18:17Z

Aglebov:

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

[[Image:toolbar.gif|The toolbar.|thumb]]

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T08:17:20Z

Aglebov: Separate subsection for toolbar

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

=== Toolbar ===

[[File:toolbar.gif|The toolbar.|thumb|right]]

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T08:15:35Z

Aglebov: Added caption to the toolbar image

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

[[File:toolbar.gif|The toolbar.|]]

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

File:Photo-Tagging-Toolbar-34.gif

2013-10-16T08:13:35Z

Aglebov: The Photo Tagging Gramplet toolbar (as appears in Gramps 3.4 under Debian Linux 7.1, GTK v2.24).

The Photo Tagging Gramplet toolbar (as appears in Gramps 3.4 under Debian Linux 7.1, GTK v2.24).

Addon:Photo Tagging Gramplet

2013-10-16T08:10:57Z

Aglebov: /* Usage */ Components of the gramplet window

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

The gramplet window consists of:
* the toolbar
* the selection area
* the list of people tagged in the image

[[File:toolbar.gif]]

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* Detection of faces across multiple images
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-16T07:59:24Z

Aglebov: /* To do */ Removed the features that have been implemented

Addons development

2013-10-08T09:06:21Z

Aglebov: /* Config */

{{man warn|Warning:|This page documents the API, methods, and best practices for developing a 3rd-party addon for Gramps 3.2 and later }}

Addons for Gramps can extend the program in many different ways. You can add any of the following [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py types] of addons:

#Report
#Quickreport
#Tool
#Importer
#Exporter
#Doc creator
#Plugin lib
#Map service
#Gramps View
#Relationships
#Gramplet
#Sidebar

Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# Develop your addon
# Create a Gramps Plugin Registration file (.gpr.py)
# Get translators to translate your addon into multiple languages
# Package your addon
# List and document your addon
# Support it through issue tracker
# Maintain the code as Gramps continues to evolve

We'll now look at each of these steps in detail.

== Develop your addon ==

The [http://svn.code.sf.net/p/gramps-addons/code/ gramps-addons] subversion repository has the following structure:

* /gramps-addons
** /trunk
*** /contrib
*** /download
** /branches
*** /gramps{{stable_branch}}
*** /gramps32
**** /contrib
**** /download

The contrib subdirectories hold the source code for the addons for a particular version. If you are working on a addon for gramps{{stable_branch}} then you should be working in gramps-addons/branches/gramps{{stable_branch}}/contrib. If you are working in gramps/trunk then you should use gramps-addons/trunk/contrib.

==== Setup the addon development tools====
These steps show how to download and work with the addon development tools.

{{man tip| 1=Tip |2=To use make.py as shown throughout this document, you may have to use: 
<pre>GRAMPSPATH=/path/to/gramps python make.py ...</pre> if the default ("../../..") is not correct.}}

# Checkout the gramps-addons files from the [https://sourceforge.net/projects/gramps-addons/ gramps-addons] project:
## cd into gramps trunk, for example:
### cd ~/gramps/trunk
## Checkout gramps-addons:
### svn co https://svn.code.sf.net/p/gramps-addons/code gramps-addons
## Change to trunk or branches/gramps{{stable_branch}} directory:
### cd gramps-addons/branches/gramps{{stable_branch}}/contrib
# Make a new project directory in gramps-addon/branches/gramps{{stable_branch}}/contrib:
## mkdir NewProjectName
# Initialize the addon:
## ./make.py init NewProjectName

===Follow the development API for your tool===
Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a Plugin]] specifically.

=== Test your addon as you develop ===
To test your addon as you develop it it is suggested that you replace your Gramps user plugin directory with a link to your addon development directory, like so:

cd ~/.gramps/gramps{{stable_branch}}/
mv plugins/* /wherever/trunk/gramps-addons/branches/gramps{{stable_branch}}/contrib/
rm -rf plugins
ln -s /wherever/trunk/gramps-addons/branches/gramps{{stable_branch}}/contrib plugins

Gramps will search this folder (and subdirectories) for .grp.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Currently, Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===

To commit your changes so that others can use your addon, follow these steps:

# Get an http://sourceforge.net account if you don't already have one.
# Request SVN write access for the gramps-addon project by emailing one of the admins of the project (listed under the gramps-addon title next to the group icon) from http://sourceforge.net/projects/gramps-addons/
# Remove the files that should not be added to SVN:
## ./make.py clean NewProjectName
# Add the project to the repository:
## svn add NewProjectName
## svn commit -m "A message describing what this addon is"

Before making additional edits to your addon, you should:

# svn update
# svn status
# svn commit -m "A message describing the changes"

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the config file already exists, it remains intact.

In the addon, you can then:

x = config.get("section.option-name1")
config.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
config.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

config = configman.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config as configman
config = configman.get_manager("grampletname")
x = config.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:
==== For Gramps 3: ====
from TransUtils import get_addon_translator
_ = get_addon_translator(__file__).gettext

==== For Gramps 4: ====

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

Gramps 3 also provides:

# ugettext
# ungettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "3.4",
version = "1.0.0",
ATTR = value,
)
</pre>

PTYPE is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and '''version'''. gramps_target_version should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. version is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '3.4',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/ here] (for example, see [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/drawreport/drawplugins.gpr.py trunk/gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are (gen/plug/_pluginreg.py):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.
The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '3.4',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print "Hello World!"
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '3.4',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '3.4',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print "Ok...", plugin.category, namespace, uistate
# return a Filter object here
return filters
</pre>

== Get translators to translate your addon into multiple languages ==

# Initialize and update the template.pot for your addon:
## ./make.py init NewProjectName
# Initialize a language for your addon (say French, fr):
## ./make.py init NewProjectName fr
# Update it from gramps and other addons:
## ./make.py update NewProjectName fr
# Edit contrib/NewProjectName/po/fr-local.po
# Compile the language:
## ./make.py compile NewProjectName
# Add or update your local language file, and commit changes:
## svn add NewProjectName/po/fr-local.po
## svn commit NewProjectName/po/fr-local.po -m "Added fr po file"

== Package your addon ==

To create a downloadable package:

python make.py build NewProjectName

That will build and copy your addon to ../download

NOTE: Running the '''make.py build''' will increment the third number in your dotted version number of all addons in the gpr.py file. Consider this number to be a "build number".

== List your addon in the Gramps Plugin Manager==
''New for Gramps 3.4'': You need to then make your addon available in listings of various languages.

'''Make sure you have already built gramps34 or trunk'''

To create a listing:

python make.py listing

That will create a series of files in the ../listings/

Then add the package to SVN:

svn add ../download/NewProjectName.addon.tgz ../listings/*
cd ..
svn commit -m "Message describing changes"

== List and document your addon on the wiki==

Document the addon in the wiki using the name '''"Addon:NewProjectName"'''.

Edit [[Plugins3.4]] or [[Plugins4.0]] and describe your addon. You can point to the addon.tgz in SVN as the downloadable file.

== Miscellaneous commands ==

To build and compile translations for all projects to their download/Addon.addon.tgz files:

python make.py build all

To compile translations for all projects :

python make.py compile all

== Support it through issue tracker ==

Visit http://www.gramps-project.org/bugs/view_all_bug_page.php and become a user. Suggest to check it regularly.

== Maintain the code as Gramps continues to evolve ==

= Resources =

* https://sourceforge.net/p/gramps-addons/ - Gramps Addons site

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]

Addons development

2013-10-08T09:03:37Z

Aglebov: /* Config */ Fixed the names of the variables

{{man warn|Warning:|This page documents the API, methods, and best practices for developing a 3rd-party addon for Gramps 3.2 and later }}

Addons for Gramps can extend the program in many different ways. You can add any of the following [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py types] of addons:

#Report
#Quickreport
#Tool
#Importer
#Exporter
#Doc creator
#Plugin lib
#Map service
#Gramps View
#Relationships
#Gramplet
#Sidebar

Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# Develop your addon
# Create a Gramps Plugin Registration file (.gpr.py)
# Get translators to translate your addon into multiple languages
# Package your addon
# List and document your addon
# Support it through issue tracker
# Maintain the code as Gramps continues to evolve

We'll now look at each of these steps in detail.

== Develop your addon ==

The [http://svn.code.sf.net/p/gramps-addons/code/ gramps-addons] subversion repository has the following structure:

* /gramps-addons
** /trunk
*** /contrib
*** /download
** /branches
*** /gramps{{stable_branch}}
*** /gramps32
**** /contrib
**** /download

The contrib subdirectories hold the source code for the addons for a particular version. If you are working on a addon for gramps{{stable_branch}} then you should be working in gramps-addons/branches/gramps{{stable_branch}}/contrib. If you are working in gramps/trunk then you should use gramps-addons/trunk/contrib.

==== Setup the addon development tools====
These steps show how to download and work with the addon development tools.

{{man tip| 1=Tip |2=To use make.py as shown throughout this document, you may have to use: 
<pre>GRAMPSPATH=/path/to/gramps python make.py ...</pre> if the default ("../../..") is not correct.}}

# Checkout the gramps-addons files from the [https://sourceforge.net/projects/gramps-addons/ gramps-addons] project:
## cd into gramps trunk, for example:
### cd ~/gramps/trunk
## Checkout gramps-addons:
### svn co https://svn.code.sf.net/p/gramps-addons/code gramps-addons
## Change to trunk or branches/gramps{{stable_branch}} directory:
### cd gramps-addons/branches/gramps{{stable_branch}}/contrib
# Make a new project directory in gramps-addon/branches/gramps{{stable_branch}}/contrib:
## mkdir NewProjectName
# Initialize the addon:
## ./make.py init NewProjectName

===Follow the development API for your tool===
Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a Plugin]] specifically.

=== Test your addon as you develop ===
To test your addon as you develop it it is suggested that you replace your Gramps user plugin directory with a link to your addon development directory, like so:

cd ~/.gramps/gramps{{stable_branch}}/
mv plugins/* /wherever/trunk/gramps-addons/branches/gramps{{stable_branch}}/contrib/
rm -rf plugins
ln -s /wherever/trunk/gramps-addons/branches/gramps{{stable_branch}}/contrib plugins

Gramps will search this folder (and subdirectories) for .grp.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Currently, Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===

To commit your changes so that others can use your addon, follow these steps:

# Get an http://sourceforge.net account if you don't already have one.
# Request SVN write access for the gramps-addon project by emailing one of the admins of the project (listed under the gramps-addon title next to the group icon) from http://sourceforge.net/projects/gramps-addons/
# Remove the files that should not be added to SVN:
## ./make.py clean NewProjectName
# Add the project to the repository:
## svn add NewProjectName
## svn commit -m "A message describing what this addon is"

Before making additional edits to your addon, you should:

# svn update
# svn status
# svn commit -m "A message describing the changes"

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the settings file already exists, it remains intact.

In the addon, you can then:

x = config.get("section.option-name1")
config.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
config.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

config = configman.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config as configman
config = configman.get_manager("grampletname")
x = config.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:
==== For Gramps 3: ====
from TransUtils import get_addon_translator
_ = get_addon_translator(__file__).gettext

==== For Gramps 4: ====

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

Gramps 3 also provides:

# ugettext
# ungettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "3.4",
version = "1.0.0",
ATTR = value,
)
</pre>

PTYPE is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and '''version'''. gramps_target_version should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. version is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '3.4',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/ here] (for example, see [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/drawreport/drawplugins.gpr.py trunk/gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are (gen/plug/_pluginreg.py):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.
The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '3.4',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print "Hello World!"
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '3.4',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '3.4',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print "Ok...", plugin.category, namespace, uistate
# return a Filter object here
return filters
</pre>

== Get translators to translate your addon into multiple languages ==

# Initialize and update the template.pot for your addon:
## ./make.py init NewProjectName
# Initialize a language for your addon (say French, fr):
## ./make.py init NewProjectName fr
# Update it from gramps and other addons:
## ./make.py update NewProjectName fr
# Edit contrib/NewProjectName/po/fr-local.po
# Compile the language:
## ./make.py compile NewProjectName
# Add or update your local language file, and commit changes:
## svn add NewProjectName/po/fr-local.po
## svn commit NewProjectName/po/fr-local.po -m "Added fr po file"

== Package your addon ==

To create a downloadable package:

python make.py build NewProjectName

That will build and copy your addon to ../download

NOTE: Running the '''make.py build''' will increment the third number in your dotted version number of all addons in the gpr.py file. Consider this number to be a "build number".

== List your addon in the Gramps Plugin Manager==
''New for Gramps 3.4'': You need to then make your addon available in listings of various languages.

'''Make sure you have already built gramps34 or trunk'''

To create a listing:

python make.py listing

That will create a series of files in the ../listings/

Then add the package to SVN:

svn add ../download/NewProjectName.addon.tgz ../listings/*
cd ..
svn commit -m "Message describing changes"

== List and document your addon on the wiki==

Document the addon in the wiki using the name '''"Addon:NewProjectName"'''.

Edit [[Plugins3.4]] or [[Plugins4.0]] and describe your addon. You can point to the addon.tgz in SVN as the downloadable file.

== Miscellaneous commands ==

To build and compile translations for all projects to their download/Addon.addon.tgz files:

python make.py build all

To compile translations for all projects :

python make.py compile all

== Support it through issue tracker ==

Visit http://www.gramps-project.org/bugs/view_all_bug_page.php and become a user. Suggest to check it regularly.

== Maintain the code as Gramps continues to evolve ==

= Resources =

* https://sourceforge.net/p/gramps-addons/ - Gramps Addons site

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]

Addons development

2013-10-08T09:02:06Z

Aglebov: /* Config */ Modified example of config initialisation

{{man warn|Warning:|This page documents the API, methods, and best practices for developing a 3rd-party addon for Gramps 3.2 and later }}

Addons for Gramps can extend the program in many different ways. You can add any of the following [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py types] of addons:

#Report
#Quickreport
#Tool
#Importer
#Exporter
#Doc creator
#Plugin lib
#Map service
#Gramps View
#Relationships
#Gramplet
#Sidebar

Writing an addon is fairly straightforward if you have just a little bit of Python experience. And sharing your addon is the right thing to do. The general steps to writing an addon and sharing your own addons are:

# Develop your addon
# Create a Gramps Plugin Registration file (.gpr.py)
# Get translators to translate your addon into multiple languages
# Package your addon
# List and document your addon
# Support it through issue tracker
# Maintain the code as Gramps continues to evolve

We'll now look at each of these steps in detail.

== Develop your addon ==

The [http://svn.code.sf.net/p/gramps-addons/code/ gramps-addons] subversion repository has the following structure:

* /gramps-addons
** /trunk
*** /contrib
*** /download
** /branches
*** /gramps{{stable_branch}}
*** /gramps32
**** /contrib
**** /download

The contrib subdirectories hold the source code for the addons for a particular version. If you are working on a addon for gramps{{stable_branch}} then you should be working in gramps-addons/branches/gramps{{stable_branch}}/contrib. If you are working in gramps/trunk then you should use gramps-addons/trunk/contrib.

==== Setup the addon development tools====
These steps show how to download and work with the addon development tools.

{{man tip| 1=Tip |2=To use make.py as shown throughout this document, you may have to use: 
<pre>GRAMPSPATH=/path/to/gramps python make.py ...</pre> if the default ("../../..") is not correct.}}

# Checkout the gramps-addons files from the [https://sourceforge.net/projects/gramps-addons/ gramps-addons] project:
## cd into gramps trunk, for example:
### cd ~/gramps/trunk
## Checkout gramps-addons:
### svn co https://svn.code.sf.net/p/gramps-addons/code gramps-addons
## Change to trunk or branches/gramps{{stable_branch}} directory:
### cd gramps-addons/branches/gramps{{stable_branch}}/contrib
# Make a new project directory in gramps-addon/branches/gramps{{stable_branch}}/contrib:
## mkdir NewProjectName
# Initialize the addon:
## ./make.py init NewProjectName

===Follow the development API for your tool===
Follow the development API for your tool, [[Report-writing_tutorial|report]], view, or [[Gramplets]]. Place all of your associated .py, .glade, etc. files in this directory. For general information on Gramps development see [[Portal:Developers]] and [[Writing a Plugin]] specifically.

=== Test your addon as you develop ===
To test your addon as you develop it it is suggested that you replace your Gramps user plugin directory with a link to your addon development directory, like so:

cd ~/.gramps/gramps{{stable_branch}}/
mv plugins/* /wherever/trunk/gramps-addons/branches/gramps{{stable_branch}}/contrib/
rm -rf plugins
ln -s /wherever/trunk/gramps-addons/branches/gramps{{stable_branch}}/contrib plugins

Gramps will search this folder (and subdirectories) for .grp.py files, and add them to the plugin list.

If you have code that you want to share between addons, you don't need to do anything special. Currently, Gramps adds each directory in which a .gpr.py is found onto the PYTHONPATH which is searched when you perform an import. Thus "import NewProjectName" will work from another addon. You should always make sure you name your addons with a name appropriate for Python imports.

=== Commit your changes ===

To commit your changes so that others can use your addon, follow these steps:

# Get an http://sourceforge.net account if you don't already have one.
# Request SVN write access for the gramps-addon project by emailing one of the admins of the project (listed under the gramps-addon title next to the group icon) from http://sourceforge.net/projects/gramps-addons/
# Remove the files that should not be added to SVN:
## ./make.py clean NewProjectName
# Add the project to the repository:
## svn add NewProjectName
## svn commit -m "A message describing what this addon is"

Before making additional edits to your addon, you should:

# svn update
# svn status
# svn commit -m "A message describing the changes"

=== Config ===

Some addons may want to have persistent data (data settings that remain between sessions). You can handle this yourself, or you can use Gramps' built-in configure system.

At the top of the source file of your addon, you would do this:

from config import config as configman
config = configman.register_manager("grampletname")
# register the values to save:
config.register("section.option-name1", value1)
config.register("section.option-name2", value2)
...
# load an existing file, if one:
config.load()
# save it, it case it didn't exist:
config.save()

This will create the file "grampletname.ini" and put in the same directory as the addon. If the settings file already exists, it remains intact.

In the addon, you can then:

x = cm.get("section.option-name1")
cm.set("section.option-name1", 3)

and when this code is exiting, you might want to save the config. In a Gramplet that would be:

def on_save(self):
cm.save()

If your code is a system-level file, then you might want to save the config in the Gramps system folder:

cm = config.register_manager("system", use_config_path=True)

This, however, would be rare; most .ini files would go into the plugins directory.

In other code that might use this config file, you would do this:

from config import config
cm = config.get_manager("grampletname")
x = cm.get("section.option-name1")

=== Localization ===

For general help on translations in Gramps, see [[Coding for translation]]. However, that will only use translations that come with Gramps, or allows you to contribute translations to the Gramps core. To have your own managed translations that will be packaged with your addon, read the rest of this page.

For any addon which you have translations into other languages, you will need to add a way to retrieve the translation. You need to add this to the top of your NewProjectName.py file:
==== For Gramps 3: ====
from TransUtils import get_addon_translator
_ = get_addon_translator(__file__).gettext

==== For Gramps 4: ====

from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.get_addon_translator(__file__).gettext

Then you can use the standard "_()" function to translate phrases in your addon.

You can use one of a few different types of translation functions:

# gettext
# lgettext
# ngettext
# lngettext
# sgettext

Gramps 3 also provides:

# ugettext
# ungettext

These have become obsolete in Gramps 4; gettext, ngettext, and sgettext always return translated strings in unicode for consistent portability between Python 2 and Python3.

See the [http://docs.python.org/3/library/gettext.html#the-gnutranslations-class python documentation] for documentation of gettext and ngettext. The "l" versions return the string encoded according to the [http://docs.python.org/3/library/locale.html#locale.setlocale currently set locale]; the "u" versions return unicode strings in Python2 and are not available in Python 3.

'''sgettext''' is a Gramps extension that filters out clarifying comments for translators, such as
_("Remaining names | rest")
Where "rest" is the English string that we want to present and "Remaining names" is a hint for translators.

== Create a Gramps Plugin Registration file ==

First, create the NewProjectName.gpr.py file. The registration takes this general form:

<pre>
register(PTYPE,
gramps_target_version = "3.4",
version = "1.0.0",
ATTR = value,
)
</pre>

PTYPE is TOOL, GRAMPLET, REPORT, QUICKVIEW, IMPORT, EXPORT, DOCGEN, GENERAL, MAPSERVICE, VIEW, or RELCALC.

ATTR depends on the PTYPE. But you must have '''gramps_target_version''' and '''version'''. gramps_target_version should be a string of the form "X.Y" version number matching Gramps X major, Y minor integer. version is a string of the form "X.Y.Z" representing the version of your addon. X, Y, and Z should all be integers.

Here is a sample Tool GPR file:

<pre>
register(TOOL,
id = 'AttachSource',
name = _("Attach Source"),
description = _("Attaches a shared source to multiple objects."),
version = '1.0.0',
gramps_target_version = '3.4',
status = STABLE,
fname = 'AttachSourceTool.py',
authors = ["Douglas S. Blank"],
authors_email = ["doug.blank@gmail.com"],
category = TOOL_DBPROC,
toolclass = 'AttachSourceWindow',
optionclass = 'AttachSourceOptions',
tool_modes = [TOOL_MODE_GUI]
)
</pre>

You can see examples of the kinds of addons [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/ here] (for example, see [http://svn.code.sf.net/p/gramps/code/trunk/gramps/plugins/drawreport/drawplugins.gpr.py trunk/gramps/plugins/drawreport/drawplugins.gpr.py]) and see the full documentation [http://svn.code.sf.net/p/gramps/code/trunk/gramps/gen/plug/_pluginreg.py here] in the comments and docstrings.

Note that this .gpr.py will automatically use translations if you have them (see below). That is, the function "_" is predefined to use your locale translations; you only need to mark the text with _("TEXT") and include a translation of "TEXT" in your translation file. For example, in the above example, _("Attach Source") is marked for translation. If you have developed and packaged your addon with translation support, then that phrase will be converted into the user's language.

=== Report plugins ===
The possible report categories are (gen/plug/_pluginreg.py):
<pre>
#possible report categories
CATEGORY_TEXT = 0
CATEGORY_DRAW = 1
CATEGORY_CODE = 2
CATEGORY_WEB = 3
CATEGORY_BOOK = 4
CATEGORY_GRAPHVIZ = 5
REPORT_CAT = [ CATEGORY_TEXT, CATEGORY_DRAW, CATEGORY_CODE,
CATEGORY_WEB, CATEGORY_BOOK, CATEGORY_GRAPHVIZ]
</pre>

Each report category has a set of standards and interface. The categories CATEGORY_TEXT and CATEGORY_DRAW use the Document interface of Gramps. See also [[Report API]] for a draft view on this.
The application programming interface or API for reports is treated at [[Report-writing_tutorial]]. For general information on Gramps development see [[Portal:Developers]] and [[Writing a plugin]] specifically.

=== General plugins ===

The plugin framework also allows you to create generic plugins for use. This includes the ability to create libraries of functions, and plugins of your own design.

==== Example: A library of functions ====

In this example, a file name library.py will be imported at time of registration (when Gramps starts):

<pre>
# file: library.gpr.py

register(GENERAL,
id = 'My Library',
name = _("My Library"),
description = _("Provides a library for doing something."),
version = '1.0',
gramps_target_version = '3.4',
status = STABLE,
fname = 'library.py',
load_on_reg = True,
)
</pre>

The code in the file library.py will be imported when Gramps begins. You can access the loaded module in other code by issuing an "import library" as Python keeps track of files already imported. However, the amount of useful code that you can run when the program is imported is limited. You might like to have the code do something that requires a dbstate or uistate object, and neither of these is available when just importing a file.

If "load_on_reg" was not True, then this code would be unavailable until manually loaded. There is no automatic mechanism in Gramps to load GENERAL plugins automatically.

In addition to importing a file at startup, one can also run a single function inside a GENERAL plugin, and it will be passed the dbstate, the uistate, and the plugin data. The function must be called "load_on_reg", and take those three parameters, like this:

<pre>
# file: library.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
print "Hello World!"
</pre>

Here, you could connect signals to the dbstate, open windows, etc.

Another example of what one can do with the plugin interface is to create a general purpose plugin framework for use by other plugins. Here is the basis for a plugin system that:

* allows plugins to list data files
* allows the plugin to process all of the data files

First, the gpr.py file:

<pre>

register(GENERAL,
id = "ID",
category = "CATEGORY",
load_on_reg = True,
process = "FUNCTION_NAME",
)
</pre>

This example uses three new features:

# GENERAL plugins can have a category
# GENERAL plugins can have a load_on_reg function that returns data
# GENERAL plugins can have a function (called "process") which will process the data

If you (or someone else) create additional general plugins of this category, and they follow your load_on_reg data format API, then they could be used just like your original data. For example, here is an additional general plugin in the 'WEBSTUFF' category:

<pre>
# anew.gpr.py

register(GENERAL,
id = 'a new plugin',
category = "WEBSTUFF",
version = '1.0',
gramps_target_version = '3.4',
data = ["a", "b", "c"],
)
</pre>

This doesn't have load_on_reg = True, nor does it have a fname or process, but it does set the data directly in the .gpr.py file. Then we have the following results:

<pre>
>>> from gui.pluginmanager import GuiPluginManager
>>> PLUGMAN = GuiPluginManager.get_instance()
>>> PLUGMAN.get_plugin_data('WEBSTUFF')
["a", "b", "c", "Stylesheet.css", "Another.css"]
>>> PLUGMAN.process_plugin_data('WEBSTUFF')
["A", "B", "C", "STYLESHEET.CSS", "ANOTHER.CSS"]
</pre>

=== Registered GENERAL Categories ===

The following are the published secondary plugins API's (type GENERAL, with the following categories):

==== WEBSTUFF ====

A sample gpr.py file:

<pre>
# stylesheet.gpr.py

register(GENERAL,
id = 'system stylesheets',
category = "WEBSTUFF",
name = _("CSS Stylesheets"),
description = _("Provides a collection of stylesheets for the web"),
version = '1.0',
gramps_target_version = '3.4',
fname = "stylesheet.py",
load_on_reg = True,
process = "process_list",
)
</pre>

Here is the associated program:

<pre>
# file: stylesheet.py

def load_on_reg(dbstate, uistate, plugin):
"""
Runs when plugin is registered.
"""
return ["Stylesheet.css", "Another.css"]

def process_list(files):
return [file.upper() for file in files]
</pre>

==== Filters ====

For example:

<pre>
register(GENERAL,
category="Filters",
...
load_on_reg = True
)
</pre>

<pre>
def load_on_reg(dbstate, uistate, plugin):
# returns a function that takes a namespace, 'Person', 'Family', etc.

def filters(namespace):
print "Ok...", plugin.category, namespace, uistate
# return a Filter object here
return filters
</pre>

== Get translators to translate your addon into multiple languages ==

# Initialize and update the template.pot for your addon:
## ./make.py init NewProjectName
# Initialize a language for your addon (say French, fr):
## ./make.py init NewProjectName fr
# Update it from gramps and other addons:
## ./make.py update NewProjectName fr
# Edit contrib/NewProjectName/po/fr-local.po
# Compile the language:
## ./make.py compile NewProjectName
# Add or update your local language file, and commit changes:
## svn add NewProjectName/po/fr-local.po
## svn commit NewProjectName/po/fr-local.po -m "Added fr po file"

== Package your addon ==

To create a downloadable package:

python make.py build NewProjectName

That will build and copy your addon to ../download

NOTE: Running the '''make.py build''' will increment the third number in your dotted version number of all addons in the gpr.py file. Consider this number to be a "build number".

== List your addon in the Gramps Plugin Manager==
''New for Gramps 3.4'': You need to then make your addon available in listings of various languages.

'''Make sure you have already built gramps34 or trunk'''

To create a listing:

python make.py listing

That will create a series of files in the ../listings/

Then add the package to SVN:

svn add ../download/NewProjectName.addon.tgz ../listings/*
cd ..
svn commit -m "Message describing changes"

== List and document your addon on the wiki==

Document the addon in the wiki using the name '''"Addon:NewProjectName"'''.

Edit [[Plugins3.4]] or [[Plugins4.0]] and describe your addon. You can point to the addon.tgz in SVN as the downloadable file.

== Miscellaneous commands ==

To build and compile translations for all projects to their download/Addon.addon.tgz files:

python make.py build all

To compile translations for all projects :

python make.py compile all

== Support it through issue tracker ==

Visit http://www.gramps-project.org/bugs/view_all_bug_page.php and become a user. Suggest to check it regularly.

== Maintain the code as Gramps continues to evolve ==

= Resources =

* https://sourceforge.net/p/gramps-addons/ - Gramps Addons site

[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category:Plugins]]
[[Category:Reports]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-08T08:56:48Z

Aglebov: /* To do */ Removed the features that have been implemented

Addon:Photo Tagging Gramplet

2013-10-05T11:07:10Z

Aglebov:

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* GIMP-like resizing of selection boxes
* Detection of faces across multiple images
* Progress bar while detection is performed
* Settings dialog
* Thumbnail images of people in the list
* Integrate with Picasa

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-10-05T10:49:06Z

Aglebov: Added Todo section

[[Image:Photo_Tagging_view.jpg|500px|thumb|right]]

== What is Photo Tagging Gramplet ==

'''Photo Tagging Gramplet''' facilitates tagging people in photographs, i.e. associating regions of images with Gramps persons.

== Features ==

* Image preview with scrolling and zooming
* List of persons tagged in the current photograph
* Adding and modifying regions and associations
* Detecting faces automatically

== Installation ==

The Photo Tagging gramplet can be installed from within Gramps. Go to {{man menu|Edit -> Preferences}} and click the {{man button|Check now}} button to see a list of plugins which are not installed on your computer.

Automatic detection of faces requires the following to be installed:
* OpenCV, its dependencies and Python bindings. This library should be available in common Linux distributions. For example, Debian package python-opencv provides the Python bindings for the library. It will require the core library packages (libopencv-*), as well as python-numpy package, to be installed. If OpenCV is not found, the automatic detection feature will be unavailable, but the gramplet should otherwise function correctly.

== Usage ==

To tag a person, select a region of the image by pressing the left mouse button in one of its corners and dragging the pointer across the desired area. A rectangular frame will mark the selected area. Use the toolbar to select an existing person or add a new person to be associated with the region.

To modify a region, press the left mouse button over one of the corners and drag it to its new position.

To associate a region with a different person, click within the region and use the toolbar buttons to select or add a person. In this case, the previous association is discarded.

== To do ==
* Good manual on this page
* GIMP-like resizing of selection boxes
* Detection of faces across multiple images
* Progress bar while detection is performed
* Settings dialog
* Thumbnail images of people in the list

[[Category:Plugins]]
[[Category:Developers/General]]
[[Category:Gramplets]]

Addon:Photo Tagging Gramplet

2013-09-15T16:30:38Z

Aglebov: Created usage section

Addon:Photo Tagging Gramplet

2013-09-14T08:42:50Z

Aglebov: Aglebov moved page PhotoTaggingGramplet to Photo Tagging Gramplet: Include spaces in the title

PhotoTaggingGramplet

2013-09-14T08:42:50Z

Aglebov: Aglebov moved page PhotoTaggingGramplet to Photo Tagging Gramplet: Include spaces in the title

#REDIRECT [[Photo Tagging Gramplet]]

Addon:Photo Tagging Gramplet

2013-09-14T08:42:22Z

Aglebov: Aglebov moved page Addon:PhotoTaggingGramplet to PhotoTaggingGramplet: Other plugin pages do not include Addon: in the title

Addon:PhotoTaggingGramplet

2013-09-14T08:42:22Z

Aglebov: Aglebov moved page Addon:PhotoTaggingGramplet to PhotoTaggingGramplet: Other plugin pages do not include Addon: in the title

#REDIRECT [[PhotoTaggingGramplet]]

Addon:Photo Tagging Gramplet

2013-09-14T08:28:16Z

Aglebov:

Addon:Photo Tagging Gramplet

2013-09-14T08:24:44Z

Aglebov: Description of PhotoTaggingGramplet