User Scripts: Noise Effect Example

The “Noise Effect” user script is a simple klf-export-type user script example distributed in the KLatexFormula sources (directory src/userscripts/noiseeffect.klfuserscript).

This simple example is meant to ease the understanding and development of klf-export-type category user scripts which are capable of generating custom output formats for export. See also the full documentation for such scripts.

This example may also serve as a simple template to start off writing a new klf-export-type category user script.

To test this script, open KLatexFormula, compile an equation and click on the “SAVE” button. Scroll down the available formats list, and you should notice the format “PNG (with noise)”. The result is:

Alternatively, you can select the copy/drag format Effects → Noisy Image (PNG) and paste/drop the output image into another application.

The main script

The file noiseeffect.py is the main script. It imports and uses the pyklfuserscript python package, which is automatically available when the script is run via klatexformula (KLF version ≥ 4.0.1).

Parsing of options is simply done with

args = pyklfuserscript.export_type_args_parser().parse_args()

First, we check if the script is being run in --query-default-settings mode.

if args.query_default_settings:
    convert = pyklfuserscript.find_executable(['convert'], [
        '/usr/local/bin',
        '/opt/local/bin',
        # add more paths to search for here
    ])
    if convert is not None: # found
        print("convert={}".format(convert))
    sys.exit()

If so, we detect the location of ImageMagick’s convert utility. (Note that pyklfuserscript.find_executable automatically searches $PATH.) If the executable is found, we print the default setting on the standard output as mandated by the user script’s behavior requirement.

Otherwise, if the script is run in normal execution mode, we need to apply the noise effect.

First, we read the settings values (executable path for convert, as well as the amount of noise to apply) from the environment variables KLF_USCONFIG_***:

convertexe = os.environ.get("KLF_USCONFIG_convert")
noisepixels = int(os.environ.get("KLF_USCONFIG_noisepixels", 3))

We check that convert was found as required, using pyklfuserscript.ensure_configured_executable which raises an error if that is not the case.

pyklfuserscript.ensure_configured_executable(convertexe, exename='convert',
                                             userscript=__file__)

Finally, we execute ImageMagick’s convert utility using subprocess.check_output:

subprocess.check_output(cmd)

Script Meta-Information (scriptinfo.xml)

The script’s meta-information is stored in a XML file named scriptinfo.xml. First we provide some basic info, including the name of the main script and the fact that it is a user script of the klf-export-type category.

<?xml version="1.0"?>
<klfuserscript-info klf-compat-version="4">
  <exe-script>noiseeffect.py</exe-script>
  <category>klf-export-type</category>
  <name>Noise effect PNG</name>
  <author>Philippe Faist, my-email@somewhere.com</author>
  <version>0.1</version>
  <license>GPL v2+</license>

Then, we provide some specifics for the script. We provide a UI file (which you can edit using Qt Designer) with a user interface for the user to modify the script’s configuration. We also declare that our script is able to provide default settings (auto-detecting the path to convert).

  <settings-form-ui>settings_form.ui</settings-form-ui>
  <can-provide-default-settings>true</can-provide-default-settings>

The scriptinfo.xml also provides settings specific for klf-export-type user scripts, providing the requested input data type (PNG), declaring the the output will be given as an output file and not on stdout, specifying export profiles for copy&paste and drag&drop, as well as declaring a single output format named png:

  <klf-export-type>
    <input-data-type>PNG</input-data-type>
    <has-stdout-output>false</has-stdout-output>
    <mime-export-profiles-xml-file>noiseeffect-export-profiles.xml</mime-export-profiles-xml-file>

    <format name="png">
      <title>PNG (with noise)</title>
      <file-name-extension>png</file-name-extension>
    </format>
  </klf-export-type>

Export Profiles (for Copy/Paste and Drag/Drop)

In order to be able to copy or drag using our custom format, we need to declare the corresponding MIME types (Linux), windows clipboard format name (Windows) or Mac UTI type or “flavor” (Mac OS X). This is done by specifying export profiles.

A user script of category klf-export-type is seen as an exporter whose name is UserScript:user-script-name, where the name is simply the name of the user script directory without the .klfuserscript suffix.

In our example, we simply define a single output profile, containing a single format (PNG). We place our profile in the sub-menu entitled “Effects”.

  <profile name="noiseeffect_png">
    <description>Noisy Image (PNG)</description>
    <in-submenu>Effects</in-submenu>

    <export-type exporter="UserScript:noiseeffect" format="png">
      <mime-type>image/png</mime-type>
      <win-format>PNG</win-format>
      <mac-flavor>public.png</mac-flavor>
    </export-type>
  </profile>

The Settings Form

The settings_form.ui is a Qt Designer UI file providing the user interface for customizing the user script’s settings. It is displayed under KLatexFormula’s settings dialog → Scripts → (select noiseeffect.klfuserscript) → Script Settings.