PicApport Plug-in Guide

Allgemeines

Versionen

  • Plug-ins wurden in Version 4.0.0 eingeführt. Alles was man benötigt ist picapport.jar oder picapport.exe mit Version 4.0 oder höher.

  • Seit Version 6.2 kann das Zielverzeichnis der Stellvertreterdateien (Shadow-Files) eingestellt werden:
    plugin.shadow.path (Pfad zu den Schattendateien/Substitutdateien(Shadow-Files) (*.$.jpg Dateien))
    Wenn gesetzt, werden beim nächsten Serverstart vorhandene S.jpg Dateien dort hin verschoben und Neue direkt dort angelegt.
    Beispiel: plugin.shadow.path=E\:\\picaport\\shadow

Verfügbare  Plug-ins

Aktuell (Feb 2015) sind folgende Plug-ins verfügbar. Aktualisierte Infos siehe: http://picapport.de/plugins.php

Download DateinameUnterstützte
Dateitypen		AnmerkungenWie wird installiert: 
PicApportDc
RawPlugin.zip

http://picapport.de/plugins.php
Basierend auf
Dave Coffin’s dcraw 

https://www.cybercom.net/~dcoffin/dcraw/
sowie Mozillas mozjpeg

https://github.com/mozilla/mozjpeg unterstützt
dieses Plug-in nahezu
alle wichtigen
RAW-Formate.
Folgende Metadaten
werden unterstützt:
title (set to
original filename)
creation date
Camera
ISO speed
Shutter
Aperture
Focal length		.3fr
Hasselblad RAW
.arw
Sony RAW
.cr2
Canon RAW
.crw
Canon RAW
.dcr
Kodak RAW
.dng
Adobe DNG
.erf
Epson RAW
.kdc
Kodak RAW
.mef
Mamiya RAW
.mos
Leaf Mosaic RAW
.mrw
Minolta RAW
.nef
Nikon RAW
.nrw
Nikon RAW
.orf
Olympus RAW
.pef
Pentax RAW
.raf
Fuji RAW
.raw
Panasonic RAW
.rw2
Panasonic RAW
.sr2
Sony RAW
.srf
Sony RAW
.srw
Samsung RAW
.x3f
Sigma RAW		Für Linux Anwender:
Die Pakete für dcraw und
cjpeg (libjpeg) müssen manuell
installiert werden:
Beispiel für Debian:
apt-get install dcraw
apt-get install libjpeg-progs

Für OS X Anwender
(1) Homebrew installieren:

/usr/bin/ruby -e „$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)„
 Es werden Command line tools von X-Code herunter geladen und installiert.Webseite für Homebrew: https://brew.sh
(2) dcraw installieren

brew install dcraw		  Die OS X Doku wurde freundlicherweise von http://itmotions.de zur Verfügung gestellt.

Als Option im
Windows-Installer
oder
Zip-Datei des Plug-ins
in das Plug-in-Verzeichnis
kopieren
PicApport neu starten
     
PicApportJavaImage
Plugin-1.0.zip

http://picapport.de/plugins.php
Einfaches Plug-in
basierend auf Java
imageIO und
TwelveMonkeys.
Unterstützte Metadaten:
title (enthält
original Dateiname)		.bmp
.gif
.png
.psd
.tif
.tiff		Aktuelle Version 1.1 Stand Dezember 2019Als Option im
Windows-Installer
oder
Zip-Datei des Plug-ins
in das Plug-in-Verzeichnis
kopieren
PicApport neu starten		 
PicApportOpenCv
VideoPluginWindows.zip
PicApportOpenCv
VideoPluginLinux.zip

http://picapport.de/plugins.php
Dieses Plugin gibt
es zur Zeit nur in der
Windows-Variante.
(Linux-Variante in Planung)
Das Plug-in basiert auf
JavaCV (
https://github.com/bytedeco/javacv)
welches wiederum
OpenCV
(http://opencv.org/)
benutzt.
Das Plug-in erzeugt
eine Stellvertreter .jpg
Datei anhand eines
Frames aus dem Video.
Unterstützte Metadaten:
title (enthält
original Dateiname)		.mp4, video/mp4
.ts, video/MP2T
.3gp, video/3gpp
.3g2, video/3gpp2
.flv, video/x-flv
.ogv, video/ogg
.avi, video/x-msvideo
.webm, video/webm
.mpg, video/mpeg
.mpeg, video/mpeg
.m2v, video/mpeg
.wmv, video/x-ms-wmv
.mov, video/quicktime
.divx,video/divx
.mkv, video/x-matroska		Dieses Plugin wurde im Oktober 2017 durch PicApportVideoThumbnailPlugin.zip ersetzt welchen nu auch unter Linux läuft.Zip-Datei des Plug-ins
abhängig vom
Betriebssystem in das
Plug-in-Verzeichnis
kopieren
PicApport neu starten		 
PicApportPdfPlugin.zip

http://picapport.de/plugins.php
Basierend auf Apache’s
PDFBox, zeigt dieses
Plug-in die 1. Seite
eines PDF-Dokumentes
angereichert mit
folgenden Metadaten:
title (set to
original filename)
creation date
creator / author
title
keywords (tags)
description
(subject)		pdf Als Option im
Windows-Installer
oder
Zip-Datei des Plug-ins
in das Plug-in-Verzeichnis
kopieren
PicApport neu starten		 
PicApportVideoThumbnailPlugin.zip
https://www.picapport.de/de/plugins.php
Unterstützte Betriebssysteme:
Linux (Debian, Raspberry, etc..)
Windows
Das Plug-in basiert auf
JavaCV (
https://github.com/bytedeco/javacv)
welches wiederum
OpenCV
(http://opencv.org/)
benutzt.
Das Plug-in erzeugt
eine Stellvertreter .jpg
Datei anhand eines
Frames aus dem Video.
Unterstützte Metadaten:
title (enthält
original Dateiname)		.mp4, video/mp4
.ts, video/MP2T
.3gp, video/3gpp
.3g2, video/3gpp2
.flv, video/x-flv
.ogv, video/ogg
.avi, video/x-msvideo
.webm, video/webm
.mpg, video/mpeg
.mpeg, video/mpeg
.m2v, video/mpeg
.wmv, video/x-ms-wmv
.mov, video/quicktime
.divx,video/divx
.mkv, video/x-matroska		Bitte stellen Sie unbedingt sicher das evtl. installierte alte Videoplugin  PicApportOpenCvVideoPluginWindows zu löschen.
Schritte um das evtl. installierte alte PicApportOpenCvVideoPluginWindows Plugin zu deinstallieren:
Den PicApport Server stoppen
Verzeichnis entfernen: .picapport/plugins/PicApportOpenCvVideoPluginWindows
Zipdatei entfernen: .picapport/plugins/PicApportOpenCvVideoPluginWindows.zip
Aktuelle Version 1.4.0 Stand Dezember 2019.
Unterstützte Plattformen:
linux/arm64
linux/armhf
linux/ppc64le
linux/x86_64
linux/x86
macOS/x86_64
Raspberry PI 4
windows/x86_64
windows/x86		Windows-Installer benutzen
oder
Zip-Datei des Plug-ins
in das Plug-in-Verzeichnis
kopieren
PicApport neu starten		 

Installation (manuell ohne Installer)

Bevor ein Plug-in installiert wird, muss bekannt sein, wo das .picapport Verzeichnis des Servers liegt.

Während des Serverstarts wird das Plug-in Verzeichnis etwa wie folgt angezeigt:: MSG  @ 14:56:03.268 Search for plugins in C:\Users\username\.picapport\plugins

Die gewünschten Plug-ins einfach in das  .picapport/plugins Verzeichnis kopieren und den PicApport Server neu starten. Fertig.

Nachdem der Server neu gestartet wurde kann anhand der aktuellen Logdatei in  .picapport/logfiles geprüft werden, ob die Plug-in Installation
erfolgreich war. Abhängig vom Plug-in Typ sollte die Logdatei etwa folgenden Text enthalten:

……..
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
……

Rot zeigt die Dateierweiterung für die dieses Plug-in registriert ist und grün den mime-type der Originaldatei.

Wie es funktioniert

Dies ist eigentlich nur für Administratoren bzw. Programmierer interessant.

Start von PicApport

  • Während des Starts wird das .picapport/plugins Verzeichnis nach .zip Dateien durchsucht.
  • Für jede gefundene .zip Datei wird ein verstecktes Verzeichnis mit dem selben Namen erzeugt und der Inhalt
    der .zip Datei hineinkopiert. Dieses Verzeichnis wird plugin-directory genannt.

  • Dann wird für jede .jar Datei im plugin-directory die Manifest.mf Datei nach einem gültigen PicApport-Plugin: Eintrag untersucht

  • Die init() Methode des Plug-ins wird gerufen (einmalig während des Starts)
    Die folgenden Informationen werden an die Init() Methode übergeben::

    • File pluginDirectory
      Verzeichnis von wo das Plug-in geladen wurde. Diese Information kann vom Plug-in genutzt werden um z.B. weitere
      Konfigurationsdaten zu speichern.
      Ein Plug-in sollte nicht auf Daten außerhalb des Plugin-Directorys zugreifen.

    • Properties props
      Wenn eine .properties Datei mit dem selben Namen wie das Plug-in existiert, wird diese von PicApport geladen und an die init() Methode 
      des Plug-ins übergeben. Ein Plug-in Entwickler sollte sicherstellen, dass props an den Konstruktor der OtherFormatsDescriptor Instanzen
      übergeben wird, die während init() erzeugt werden.
      Das Plug-in kann die Properties nutzen um weitere Konfigurationsdaten zu speichern. Siehe auch PicApportPdfPlugin-src.zip wie dies verwendet werden kann.
      Beispiel: 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

      Der Eintrag menudownload.text[.iso language] kann verwendet werden um den Text des „Download-Buttons“ in der PicApport Slideshow anzupassen.
      Ist kein Text für die aktuelle Sprache konfiguriert, wird der Eintrag (menudownload.text) benutzt. (Solle immer Englisch sein)

    • IPicApportPlugInLogger logger
      Der logger sollte in den privaten Memberdaten der Plug-in Instanz gesichert werden und für Debug Ausgaben verwendet werden.

  • Die init() Methode muss mindestens eine OtherFormatsDescriptor Instanz erzeugen und in  List<OtherFormatsDescriptor> zurückgeben.

    Descriptoren erzeugen
    return  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),   
                 });

Während des Scannens der Foto Verzeichnisse

  • Wenn PicApport ein Foto-Verzeichnis scannt, werden alle nicht Jpeg-Dateien geprüft ob dafür ein Plug-in registriert wurde.
  • Wurde ein Plug-in registered:
    • PicApport prüft ob eine Stellvertreter-Datei (substitute-file) existiert 
      Die Stellvertreter-Datei ist die jpg Repräsentation der Originaldatei. PicApport fügt .$.jpg an den Namen der Originaldatei an um den Stellvertreter Namen zu erzeugen.
      Wenn die Stellvertreter-Datei nicht existiert oder älter ist als die Originaldatei wird die createJpegFile() Methode des Plug-ins gerufen um die Stellvertreter-Datei zu erzeugen.
      Die folgenden Informationen werden an die createJpegFile() Methode übergeben:

      • File otherFormatFile
        Vollständiger Pfad der Originaldatei

      • File jpegFileToCreate
        Vollständiger Pfad der zu erzeugenden Stellvertreter-Datei

      • CcXMPMetaData metaDataIn
        Optionale Metadaten für die Stellvertreter-Datei. Sind keine Metadaten verfügbar sollte createJpegFile() null zurückgeben.
        Sind Metadaten verfügbar, sollten diese in metaDataIn  gesetzt werden und  metaDataIn sollte anstatt null zurückgegeben werden.
        Siehe auch: Javadoc http://picapport.de/plugins/javadoc/ für weitere Details von CcXMPMetaData .

Programmierung

Plug-ins werden in Java erstellt.

Es muss sichergestellt sein, dass ein picapport.jar mindestens mit Version 4.0.0 im classpath des Compilers eingetragen ist

Ein PicApport Plug-in zu erstellen ist sehr einfach. Einfach eine Java-Klasse erstellen die zwei Methoden implementiert:

  • public List<OtherFormatsDescriptor> init(File pluginDirectory, Properties props, IPicApportPlugInLogger logger)

  • public CcXMPMetaData createJpegFile(File otherFormatFile, File jpegFileToCreate, CcXMPMetaData metaDataIn)

Siehe auch: Javadoc http://picapport.de/plugins/javadoc/ für weitere Details.

Beispiel PicApport Plug-in for .gif and .png Unterstützung

PicApportJavaImagePlugin
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);
  }
}

Die Manifest Datei

Ein PicApport Plug-in wird durch eine .jar Datei repräsentiert. Diese .jar Datei MUSS eine Manifest.mf Datei enthalten mit einem PicApport-Plugin: Eintrag in welchem die Klasse deklariert wird, welche de.contecon.picapport.plugins.otherformats.IOtherFileFormat implementiert.

Manifest.mf
Manifest-Version: 1.0
Sealed: true
PicApport-Plugin: de.contecon.picapport.plugin.javaimage.JavaImagePlugin

Die Plug-in .zip Datei

Als letzter Schritt wird eine .zip Datei für das Plug-in erstellt. Der Dateiname sollte dem Klassennamen des Plug-ins entsprechen.

Die .zip Datei muss mindestens folgende Dateien beinhalten::

  • Die .jar Datei des Plug-ins
  • Die.properties Datei des Plug-ins

Optionaler Inhalt könnte sein::

  • Weitere .jar Dateien die vom Plug-in benötigt werden
  • Lizenz Informationen
  • Weitere Dateien