PicApport Plug-in Guide
General
Version
Plug-ins have been introduced in PicApport 4.0.0. So all you need as a picapport.jar or picapport.exe with Version 4.0 or later.
Available Plug-ins
Currently (Feb 2015) we offer the following plug-ins. Please check http://picapport.de/plugins.php for updates.
PicApportJava Simple plug-in based The following meta-data
|
|
| |||
PicApport Based on Apaches
|
| ||||
PicApportDc Based on Dave The following
|
| For Linux users: Example for Debian:
For OS X users (1) Install Homebrew:
This will download and install command line tools from X-Code. Webseite for Homebrew: https://brew.sh (2) install dcraw
|
| ||
PicApportVideoThumbnailPlugin.zip This plugin supports
The Plug-in creates The following meta-data
|
| Please make sure that you remove the old PicApportOpenCvVideoPluginWindows plugin if it was installed. Steps to uninstall the PicApportOpenCvVideoPluginWindows plugin:
|
| ||
PicApportOpenCv Currently, only the The Plug-in creates The following meta-data
|
| This Plugin has been replaced by the PicApportVideoThumbnailPlugin.zip released in October 2017 |
|
Installation
Before you install a plug-in make sure that you know where your .picapport directory of your installation is located.
During server-startup the plug-in directory will be displayed like this: MSG @ 14:56:03.268 Search for plugins in C:\Users\username\.picapport\plugins
Copy one ore more the plug-in.zip file(s) to the .picapport/plugins directory and (re)start the PicApport server.
After restarting the server you can check the current logfile in the .picapport/logfiles directory if a plug-in has been installed successfully.
Depending on the plug-in-type the logfile should contain something like this:
……..
MSG @ 14:53:18.045 Plugin loaded: PicApport GIF plugin 1.0 (c) 2014 Contecon Software GmbH .gif image/gif (hideSubstitutes=true) implements IOtherFileFormat
MSG @ 14:53:18.045 Plugin loaded: PicApport PNG plugin 1.0 (c) 2014 Contecon Software GmbH .png image/png (hideSubstitutes=true) implements IOtherFileFormat
MSG @ 14:53:18.047 Plugin loaded: PicApport PDF plugin 1.0 (c) 2015 Contecon Software GmbH .pdf application/pdf (hideSubstitutes=true) implements IOtherFileFormat
……
Where red shows the file-extension handled by this plug-in and green the mime-type of the original file.
How it works
If you are not a programmer this is may be not interesting for you
During PicApport startup
- When PicApport starts it checks the .picapport/plugins directory for existing .zip files.
- For each .zip file a hidden directory with the same name will be created an the content
of the .zip file will be copied to this directory. This directory is called plugin-directory. Then for each .jar file in the plugin-directory the Manifest.mf file will be check for a valid PicApport-Plugin: entry
- The init() method of the plug-in will be called (only one time during server startup)
The following information is passed to the init() method:File pluginDirectory
The path to the directory where this plug-in was loaded from. This Information
may be used by the plug-in to load more configuration data.
A plug-in should not be dependent on information outside this directoryProperties props
If a .properties file with the same name as the plug-in exists, it will be loaded by PicApport and passed to the init() method.
Also make sure that props is passed to the constructor method of the OtherFormatsDescriptor created during the init phase.
The plug-in may use this file to store additional configuration data. See our PicApportPdfPlugin-src.zip plug-in how this can be used.
Example PicApportPdfPlugin.properties:# if resolution is not set the default will be 96
pdf.resolution=96
menudownload.text=Show PDF
menudownload.text.en=Show PDF
menudownload.text.de=PDF anzeigen
keywords=$nonjpg
The menudownload.text[.iso language] may be used to set the download text of the original file in the PicApport slideshow.
If a text for the current language does not exist the default text(menudownload.text) will be used. (Should be English)IPicApportPlugInLogger logger
The logger should be saved in a private member of the plug-in and should be used for debug output if required.
The init() method should return at least one OtherFormatsDescriptor instance element in the List<OtherFormatsDescriptor> returned.
Create the descriptorreturn
Arrays.asList(
new
OtherFormatsDescriptor[] {
new
OtherFormatsDescriptor(
".gif"
,
// One of the file extensions this plugin will be called
"image/gif"
,
// Mime type of the original file
true
,
// If true, substitute files will be hidden
"PicApport GIF plugin"
,
// Name of the plug-in
"(c) 2014 Contecon Software GmbH"
,
// Copyright
"1.0"
,
// Version
props),
// always use props passed to the init() method
new
OtherFormatsDescriptor(
".png"
,
"image/png"
,
true
,
"PicApport PNG plugin"
,
"(c) 2014 Contecon Software GmbH"
,
"1.0"
,
props),
});
During scanning of the photo directories
- When PicApport scans the photo directory’s it checks all non-jpg files if a plug-in has been registered.
- If a plug-in has been registered:
- PicApport checks if the substitute file exists
A substitute file is the jpg representation of the original file. PicApport adds .$.jpg to the original file to get the substitute filename.
If the substitute file does not exist or is older than the original file the createJpegFile() method of the plugin will be called to create the substitute file.
The following information is passed to the createJpegFile() method:File otherFormatFile
Path to the original FileFile jpegFileToCreate
Path to the substitute file that should be createdCcXMPMetaData metaDataIn
Optional meta-data added to the substitute jpg file. If no meta-data is available createJpegFile() method should return null.
If meta-data is available it should be added to metaDataIn and metaDataIn should be returned instead of null.
see: Javadoc on http://picapport.de/plugins/javadoc/ for more details of CcXMPMetaData .
- PicApport checks if the substitute file exists
Programming
Plug-ins are programmed in the Java programming language.
Before you start,make sure that you have downloaded a picapport.jar with at least version 4.0.0. When you compile your plug-in make sure that picapport.jar is in your classpath
Creating a PicApport plug-in is very simple. Basically you just have to implement two Methods in a Java Class:
public List<OtherFormatsDescriptor> init(File pluginDirectory, Properties props, IPicApportPlugInLogger logger)
public CcXMPMetaData createJpegFile(File otherFormatFile, File jpegFileToCreate, CcXMPMetaData metaDataIn)
see: Javadoc on http://picapport.de/plugins/javadoc/ for more details.
Sample PicApport plug-in for .gif and .png support
package de.contecon.picapport.plugin.javaimage; import java.awt.Color; import java.awt.Graphics2D; import java.awt.image.BufferedImage; import java.io.File; import java.util.Arrays; import java.util.Calendar; import java.util.Date; import java.util.List; import java.util.Properties; import javax.imageio.ImageIO; import de.contecon.imageutils.CcXMPMetaData; import de.contecon.picapport.plugins.IPicApportPlugInLogger; import de.contecon.picapport.plugins.otherformats.IOtherFileFormat; import de.contecon.picapport.plugins.otherformats.OtherFormatsDescriptor; /** * This is a simple example of a PicApport plugin. * To compile this at least a picapport.jar version 3.3 or newer is required. * This Plugin supports .gif and .png files. * * PicApport plugins for other fileformats must implement de.contecon.picapport.plugins.otherformats.IOtherFileFormat * * Please have in mind that a valid PicApport plugin .jar files MUST have a Manifest.mf file * with a PicApport-Plugin: entry. * * Example Manifest.mf: * <pre> * Manifest-Version: 1.0 * Sealed: true * PicApport-Plugin: de.contecon.picapport.plugin.javaimage.JavaImagePlugin * <pre> * 10.02.2015 * @author Eric */ public class JavaImagePlugin implements IOtherFileFormat { private IPicApportPlugInLogger logger; @Override public List<OtherFormatsDescriptor> init(File pluginDirectory, Properties props, IPicApportPlugInLogger logger) { this .logger = logger; return Arrays.asList( new OtherFormatsDescriptor[] { new OtherFormatsDescriptor( ".gif" , "image/gif" , true , "PicApport GIF plugin" , "(c) 2014 Contecon Software GmbH" , "1.0" , props), new OtherFormatsDescriptor( ".png" , "image/png" , true , "PicApport PNG plugin" , "(c) 2014 Contecon Software GmbH" , "1.0" , props), }); } @Override public CcXMPMetaData createJpegFile(File otherFormatFile, File jpegFileToCreate, CcXMPMetaData metaDataIn) throws Exception { BufferedImage bi = ImageIO.read(otherFormatFile); BufferedImage bufferedImageJpg = new BufferedImage(bi.getWidth(), bi.getHeight(), BufferedImage.TYPE_INT_RGB); Graphics2D g2 = bufferedImageJpg.createGraphics(); g2.drawImage(bi, 0 , 0 , bufferedImageJpg.getWidth(), bufferedImageJpg.getHeight(), Color.WHITE, null ); javax.imageio.ImageIO.write(bufferedImageJpg, "jpeg" , jpegFileToCreate); g2.dispose(); Calendar dateCreated = Calendar.getInstance(); dateCreated.setTime( new Date(otherFormatFile.lastModified())); metaDataIn.setCreationDate(dateCreated); metaDataIn.setTitle(otherFormatFile.getName()); metaDataIn.setDescription( "PicApport JavaImagePlugin" ); return (metaDataIn); } } |
The Manifest File
A PicApport plug-in is represented and installed by a .jar file. This .jar MUST have a Manifest.mf file with a PicApport-Plugin: entry where the class implementing the de.contecon.picapport.plugins.otherformats.IOtherFileFormat is delared.
Manifest-Version: 1.0 Sealed: true PicApport-Plugin: de.contecon.picapport.plugin.javaimage.JavaImagePlugin |
The plug-in .zip file
The last step is to create a zip file for the plug-in. The filename should be the classname of the plug-in.
The .zip file should contain at least:
- The .jar file of the plug-in
- The.properties-file of the plugin
Optional content can be:
- Other .jar files required by the plugin
- License information files
- Any other files