Skip to content

Documentation

Jump to bottom
Max Paperno edited this page Aug 27, 2023 · 3 revisions

NOTE - THIS DOCUMENTATION IS INCOMPLETE!
Many new actions and features have been added in recent versions which are not yet documented. We're working on it!

See also the Examples page.

Table of Contents

Plugin Settings

Plugin Settings

  • Default Icon Size - Size of non-layered icon images, created with single "Draw" actions, in pixels. For layered icons the size can be specified per-icon.

    • This can be set to a single value for both width and height (eg. 128) or separate values using <width> x <height> or <width>, <height> format (eg. 128 x 256 or 128, 256).

  • Default Image File Path - Base directory to use when loading image files specified using a relative path. When left empty, the default is Touch Portal's configuration, or "data," directory for the current user (this path is shown in TP's Settings -> Info window).

  • Enable GPU Rendering by Default - Enables or disables using hardware acceleration (GPU), when available, for generating icon images.

    • Enter a 1 (one) to enable GPU usage, 0 (zero) to disable.

    This setting can be also be overridden per layered icon, in the "Generate" action.

    When disabled, all image drawing/rendering happens on the CPU, which may be slower and/or produce slightly different results in some cases. GPU rendering is only supported on some hardware/OS/drivers, and is disabled on others regardless of this setting.

    Note that at least some CPU will be used when generating icons in any case, most notably for image file loading and final output PNG compression.

    Changing this setting does not affect any icons already generated (to reset, either delete icons with Plugin Actions action or restart the plugin from the settings screen).

  • Default Output Image Compression Level - Sets or disables the default image compression level of generated icons.

    • This can be set to a number between 1 (low compression) and 9 (high compression), or 0 (zero) to disable compression entirely.

    This option can be also be overridden per icon, in the "Generate" action.

    Compression affects the final image data size which will be sent to the TP device for display. The higher the compression level, the smaller the final size. However, compression uses CPU resources, proportional to the compression level (higher level means more CPU use) and may produce lower quality images.

    Large image data sizes may impact the performance of the connected TP device to the point that it becomes unusable due to the lag. This setting can be adjusted to fine-tune the impact of dynamic icon generation on your computer vs. efficient delivery of images to the TP device.

    Changing this setting does not affect any icons already generated (to reset, either delete icons with Plugin Actions action or restart the plugin from the settings screen).

Available Actions

Action List

Draw - Simple Round Gauge

Simple Round Gauge

Properties

  • Name: Can be any unique name for this image, it will become the State created by the plugin
  • Shadow: On or Off - do you want a light shadow behind your round gauge
  • Shadow Color: pick a color any color, only will display if Shadow is On
  • Indicator Color: Color of the main round gauge indicator
  • Highlight: On or Off - do you want a slight glow/highlight around the round guage (same color as indicator)
  • Starting At Degree: 180 (default) - can be any number 0 - 360, 0 is right middle of circle
  • Value: the value you want to represent - precentage 0 - 100
  • Cap Style: butt|round|square - What do you want the end of the indicator to look like (round looks best)
  • Background Color: pick a color any color, if you want no background, set Opacity to 0 in the color selector
  • Direction: clockwise|counter clockwise - which way do you want the gauge to go around the circle.

Draw - Simple Bar Graph

Simple Bar Graph

Properties

  • Name: Can be any unique name for this image, it will become the State created by the plugin
  • Background: On or Off - do you want the graph on a background color
  • Background Color: pick a color any color, only will display if Background is On
  • Bar Color: pick a color any color, this is the color of the bars being drawn
  • Value: the value you want to represent - percentage 0 - 100
  • Bar Width: 10px (default) - any number of pixels you want the bar graph to look like, 1-256 px

Draw - Image

Image Stack

This Action allow you to dynamically create icons from one or more source images. For example images can be "stacked," or overlaid, on top of each other, and/or be transformed at the same time to allow for rotation, movement, or scaling based on static or dynamic input values. In other words is allows for some basic animation effects using any image files which you provide. For example a clock face with 3 rotating hands on top.

Properties

  • Icon Name: Can be any unique name for this image, it will become the State created by the plugin.
  • Image File: Path to an image file. This can be a full (absolute) path on your system, or relative.
    • Relative paths are resolved according to this plugin's "Default Image Files Path" setting in Touch Portal. By default this is your user's Touch Portal "data" directory (see Settings section for details). This means a relative path with default settings gets you to the base data folder, so for example "iconpacks/Touch Portal Essentials Classics/CameraWhite.png" gets an image from one of the default icon packs.
    • Supported image formats are: PNG, JPEG, SVG, GIF, WebP, TIFF, AVIF
  • Resize Fit: How to resize the source image to fit into the icon's final dimensions. The options are:
    • contain - Shrinks or expands the image to fit the image's largest dimension, keeping aspect ratio. The image may be "letterboxed" if not square.
    • cover - Shrinks or expands the image to fit the image's smallest dimension, keeping aspect ratio. The image may be clipped if it is not square.
    • fill - Shrinks or expands the image to completely cover the icon size, ignoring aspect ratio. The image may become distorted if it is not square.
    • scale-down - Same as contain option except it will never expand an image if it already fits into the icon dimensions.
    • none - Do not resize the source image at all.
  • Image Transformation Options:
    • Offset: Moves (translates) the image left/right/up/down relative to the other images in the stack.
      • Two values can be provided separated by a colon (:), semicolon (;), single quote ('), or backtick (`).
      • The first value is for the X (horizontal) axis, the second for the Y (vertical) axis. If only one value is provided then it is used for both X and Y coordinates.
      • A value of 100 (%) is equivalent to one full dimension of the produced image (as specified in the Size field). Positive values move the image to the right/down, and negative values move it left/up. For example a translation of (50 : -50) will position the image in the upper right quarter of the resulting composition.
    • Rotate: Rotates the image around the center. A value of 100 (%) equals one full revolution of 360°. 0 means no rotation is applied (image is unchanged).
      • Positive values rotate clockwise, negative goes counter-clockwise.
      • Values greater or less than +/- 100 are allowed (they will just wrap back around to a valid angle).
    • Scale: Resizes the image width and/or height relative to the requested icon size.
      • Two values can be provided here as well (see "Translate" above for syntax). The first value scales the image horizontally, the second one vertically. If only one value is provided, it is used for both dimensions.
      • A value of 100 (%) is equivalent to one full dimension of the produced image (as specified in the Icon Size field). Positive values enlarge the image and negative values shrink it. For example a scale of (50 : -50) will make the image 1.5 times wider and half as tall as the Image Size value (the result would be clipped on the sides).
    • Order: Dictates the order in which the transformation steps (specified above) are applied to the image.
      • The order in which the image rotation/translation/scaling takes place can make a large difference in the result. Depending on what you are trying to achieve and the images you're using, it may be desirable to change this order on an image-by-image basis.
      • For example if you first rotate and then translate an image it effectively changes the center point around which the image rotates (eg. from its bottom edge vs. the default of center). But if you reverse the order, the image will still rotate around its center point, but will do so at whatever new coordinates you moved it to.
      • As another example if you scale an image before moving (translating) it, it effectively scales the movement amount as well. So if the image is downscaled to 50% then moved 100% to the right, its center point will be on the edge of the produced icon instead the whole image being completely out of the frame as it would be if you translated it first.

Image Notes

  • The image overlay/stacking feature is designed to work best with images which are all the same size, ideally of square proportions. It is best that the images are prepared so when the overlay stack is constructed or animated, minimal transformation is needed to achieve the desired result. For example a clock hand image be should positioned within the overall square so that simply rotating the whole image around the center point will make it land at the right place on the clock face. Having to move (translate) the hand image into position before/after rotating it would be a lot less efficient and more difficult to set up.
  • Input images are cached to improve performance. (Not to be confused with the resulting icons, which are not cached by the plugin.) This means if you modify an image used in one of these actions, the change will not show up until one of the following:
    1. The image file name or location (path) is changed (to a name/location that hasn't been cached yet).
    2. The requested Icon Size is changed (to a value that hasn't been cached yet).
    3. The cache is cleared with the provided plugin action: Dynamic Icons -> System Actions -> Clear the Source Image Cache
    4. The plugin (or Touch Portal) is restarted.

General Information

  • Math operations in action value fields.
    Almost all the text data field types (with the + icon) will accept JavaScript expressions which are evaluated by the plugin itself (after TP sends the action data to the plugin).
    This is actually a pretty important feature and makes the whole thing a lot more practical.

    • Keep in mind/consider that any Touch Portal value (state, local or global Value, etc) can be used in the value expressions as inputs. So any of this math can be performed on those values right in the action data fields. First select the state/value(s) you want to calculate with, then add the math bits.
    • Supports the full range of basic arithmetic operations one may expect, but also logical, bitwise and conditional (ternary) operators, "regular expressions" (RegEx), and quite a bit more.
    • Supports JavaScrip's Math functions and constants, for rounding, min/max range control, algebra, trigonometry, and more.
      • See the MSDN Math documentation for a full reference. Function names must be prefixed with Math. as shown in the examples.
    • As a very basic example: A button which requests a new dynamic icon on each press with a random rotation value. After specifying the icon name, desired size, and an image file, you could put the following in the "Rotate" value field: Math.random() * 100. "Math.random()" produces a random number between 0 and 1, which we then multiply by 100 to get a random final value (percentage of 360°).

  • Image processing can be quite "expensive" computationally and it is possible to overload even a very fast computer with a lot of image requests at the same time. Having a real GPU (graphics processor) installed will offload some of the work. And remember all that generated image data has to be sent to TP desktop and then to the client device (possibly over slow WiFi). Do not expect miracles. Do use a fast wired connection to your TP client device if you can.

  • Have fun and experiment!!!

Clone this wiki locally