1#@gmic 2#-------------------------------------------------------------------- 3# 4# This file illustrates how to set up a correct G'MIC filter source 5# (e.g. to be included in 'gmic-community/include/' afterwards). 6# 7# It contains toy filters in various categories to show how things are 8# working. This should be a good basis for creating your own filters 9# for the G'MIC plug-in. 10# 11#--------------------------------------------------------------------- 12# ^ Remove this header when creating your G'MIC filter source ! ^ 13# ^ But keep the first line '#@gmic' (mandatory), it identifies the file 14# as a G'MIC filter source ^ 15 16#---------------------------------------------------------------------- 17# 18# File : john_doe.gmic <-- Put your name as the filename. 19# ( G'MIC commands file ) 20# 21# Description : A template file for creating new G'MIC filters. 22# 23# Copyright : John Doe (jd) 24# ( http://en.wikipedia.org/wiki/John_Doe/ ) 25# 26# License : CeCILL v2.0 27# ( http://cecill.info/licences/Licence_CeCILL_V2-en.html ) 28# 29# This software is governed by the CeCILL license under French law and 30# abiding by the rules of distribution of free software. You can use, 31# modify and/ or redistribute the software under the terms of the CeCILL 32# license as circulated by CEA, CNRS and INRIA at the following URL 33# "http://cecill.info". 34# 35# As a counterpart to the access to the source code and rights to copy, 36# modify and redistribute granted by the license, users are provided only 37# with a limited warranty and the software's author, the holder of the 38# economic rights, and the successive licensors have only limited 39# liability. 40# 41# In this respect, the user's attention is drawn to the risks associated 42# with loading, using, modifying and/or developing or reproducing the 43# software by the user in light of its specific status of free software, 44# that may mean that it is complicated to manipulate, and that also 45# therefore means that it is reserved for developers and experienced 46# professionals having in-depth computer knowledge. Users are therefore 47# encouraged to load and test the software's suitability as regards their 48# requirements in conditions enabling the security of their systems and/or 49# data to be ensured and, more generally, to use and operate it in the 50# same conditions as regards security. 51# 52# The fact that you are presently reading this means that you have had 53# knowledge of the CeCILL license and that you accept its terms. 54# 55#------------------------------------------------------------------------------ 56# ^ This is a regular header. Of course you can change the License with a more 57# or less restrictive rules (non-commercial for instance). 58 59#------ Syntax rules for a G'MIC command file : 60# 61#*** General syntax : 62# 63# - Each line starting with 'command_name :' starts a new definition of the G'MIC custom command 'command_name'. 64# - Each line starting with '#' is a comment line. 65# - Any other line is considered as the continuation of a previously started G'MIC custom command. 66# 67#*** Specific rules for the command-line interface 'gmic': 68# 69# - A comment line starting with '#@cli' will be parsed by 'gmic' to display help for 70# G'MIC custom commands (when invoked with option 'h'). More precisely : 71# 72# _ '#@cli :: subsection' defines a new command subsection in the displayed help. 73# _ '#@cli command_name : arguments_format1 : arguments_format2 : ... : (qualifier)' 74# starts a new command description. 75# _ '#@cli : description' add a new description line to the current command description. 76# 77#*** Specific rules for the universal plug-in : 78# 79# - A comment line starting with '#@gui' will be parsed by the plug-in to define the filters tree. 80# - A comment line starting with '#@gui_xx' will define a filter only for a specific language 'xx' 81# (e.g. 'en','fr'...). 82# - A comment line starting with '#@gui_xx hide(/Filter or folder name)' will hide the existing 83# filter of folder for the locale 'xx'. 84# - More precisely, the syntax of a '#@gui' comment line is : 85# 86# '#@gui Folder name' 87# 88# or 89# 90# '#@gui Command name : command, preview_command, parameter = typedef, parameter2 = typedef' 91# '#@gui : parameter3 = typedef, parameter4 = typedef ...., parameterN = typedef' 92# 93# where : 94# 95# 'command' is the G'MIC command name called to process the image. 96# 97# 'preview_command' is the G'MIC command name called to process the preview. 98# 99# Note that you can optionally specify a float-valued factor>=0 between parentheses at the end of 100# the 'preview_command' to force the default zoom factor used by the preview for this filter. 101# Use (0) for a 1:1 preview, (1) for previewing the whole image, (2) for 1/2 image and so on... 102# You can also put an additional '+' sign after the parenthesis to specify the rendered preview 103# is still accurate for different zoom factors. 104# 105# 'parameter = typedef' tells about the names, types and default values of the filter parameters. 106# 107# 'typedef' can be : 108# 109# _ 'bool(default_value={ 0 | 1 | false | true })' : Add a boolean parameter (0 or 1) (as a checkbutton). 110# _ 'button(_alignment)' : Add a boolean parameter (0 or 1) (as a button). 111# _ 'choice(_default_indice,Choice0,..,ChoiceN)' : Add a integer parameter (as a combobox). 112# _ 'color(R,_G,_B,_A)' : Add R,G,B[,A] parameters (as a colorchooser). 113# _ 'point(_X,_Y,_removable={ -1 | 0 | 1 },_burst={ 0 | 1 },_R,_G,_B,_[-]A,_radius%,_is_visible={ 0 | 1 })' : 114# Add X,Y parameters (as a moveable point over the preview). 115# _ 'value(value)' : Add a pre-defined value parameter (not displayed). 116# _ 'file[_in,_out](_default_filename)' : Add a filename parameter (as a filechooser). 117# _ 'float(default_value,min_value,max_value)' : Add a float-valued parameter (as a float slider). 118# _ 'folder(_default_foldername)' : Add a foldername parameter (as a folderchooser). 119# _ 'int(default_value,min_value,max_value)' : Add a integer parameter (as an integer slider). 120# _ 'link(_alignment,_label,URL)' : Display a URL (do not add a parameter). 121# _ 'note(_label)' : Display a label (do not add a parameter). 122# _ 'text(_is_multiline={ 0 | 1 },_default text)' : Add a single or multi-line text parameter (as a text entry). 123# _ 'separator()' : Display an horizontal separator (do not add a parameter). 124# 125# Type separators '()' can be replaced by '[]' or '{}' if necessary (for instance if parentheses are required in 126# an argument of the typedef, e.g in a text). You can also replace 'typedef' by '_typedef' to tell the plug-in not 127# to update the image preview when the corresponding parameter is modified. 128# 129# Use '_none_' as a special command or preview_command to tell the plug-in that the entry requires no G'MIC call. 130# 131# A G'MIC command can return new values for each parameter of the filter, into the status (see command 'status'). 132# To do so, the returned status must follow the syntax : {params1}{params2}{..}{paramsN} where N must be exactly 133# equal to the number of parameters for the current filter. 134# 135# A G'MIC command can also specify the blending mode, the opacity and the position of each of the output image 136# (i.e. layer in the plug-in). To do so, set the image name to something like 'mode(grainmerge),opacity(50),pos(30,50),name(name)'. 137# - Blending mode name should be the same as the argument of the 'blend' command. 138# - Opacity is a float number in [0,100]. 139# - X and Y positions are integers. 140# - 'name' is the layer name. 141# 142#----------------------------------------------------------------------------------------------------------------------- 143 144# The filters below will go the the 'Testing / John Doe' category. This is a good 'standard' location 145# for placing new filters that are still in testing mode. 146# Once considered as stable, such filters can be moved to one of the existing (considered as 'stable') category 147# (e.g. 'Artistics' or 'Details', or moved in a brand new category if no one corresponds to the topic of the filters. 148 149#------------------------------------ 150#@gui <b>Testing</b> 151#@gui <i>John Doe</i> 152#------------------------------------ 153 154#@gui About : _none_, jd_about 155#@gui : note = note{" 156#@gui : <span foreground="purple">( <b>J</b>ohn Doe's <b>F</b>ilter <b>S</b>et for <b>G'MIC</b>)</span>\n\nis proposed to you by"} 157#@gui : note = link("John Doe","http://en.wikipedia.org/wiki/John_Doe/") 158#@gui : note = link{"( Affiliation )","http://www.affiliation_url.org"} 159#@gui : note = note{"\n"} 160#@gui : sep = separator() 161#@gui : note = note{" 162#@gui : The source code of this set of filters is available at :"} 163#@gui : note = link("http://www.filters_url.org/template.gmic") 164#@gui : "} 165#@gui : sep = separator() 166jd_about : 167 fx_logo "John Doe's Filters" 168 169# ^ Please prefix all your G'MIC commands with your initials, so it reduce possible name conflicts with commands defined in other sources ! 170 171#@gui Toy filter : jd_toyfilter, jd_toyfilter_preview(0) 172#@gui : Smoothness = float(0,0,10) 173#@gui : Mirror = choice("X","Y","XY") 174#@gui : sep = separator(), Preview type = choice("Full","Forward horizontal","Forward vertical","Backward horizontal","Backward vertical","Duplicate top","Duplicate left","Duplicate bottom","Duplicate right","Duplicate horizontal","Duplicate vertical","Checkered","Checkered inverse"), Preview split = point(50,50,0,0,200,200,200,0,10,0) 175#@gui : sep = separator(), note = note("<small>Author : <i>First_name Last_name</i>. Latest update: <i>12/29/2010</i>.</small>") 176jd_toyfilter : 177 blur $1 178 if $2==0 mirror x 179 elif $2==1 mirror y 180 else mirror xy 181 endif 182 183jd_toyfilter_preview : 184 gui_split_preview "jd_toyfilter ${1--2}",${-3--1} 185 186#@gui __ 187# ^ The line above allows to goes 2 levels up, so exit the 'Testing / John Doe' folders. 188# Now, the parser considers you are located in the root path of the filter tree. 189#---------------------------------------------------------------------------------------- 190 191 192# The filters below will go the the 'Various' folder. 193# Put filters in regular locations only when you are sure that everything is working well, 194# as many users will possibly experience your filter ! 195 196#------------------------------------ 197#@gui <b>Various</b> 198#------------------------------------ 199#@gui Extr'artistic : jd_xtrartistic, jd_xtrartistic_preview(1) 200#@gui : Smoothness = float(10,0,30) 201#@gui : Sharpness = float(100,0,500) 202#@gui : sep = separator(), Preview type = choice("Full","Forward horizontal","Forward vertical","Backward horizontal","Backward vertical","Duplicate top","Duplicate left","Duplicate bottom","Duplicate right","Duplicate horizontal","Duplicate vertical","Checkered","Checkered inverse"), Preview split = point(50,50,0,0,200,200,200,0,10,0) 203#@gui : sep = separator(), note = note("<small>Author : <i>First_name Last_name</i>. Latest update: <i>12/29/2010</i>.</small>") 204jd_xtrartistic : 205 blur $1 sharpen {100*$2} 206 207jd_xtrartistic_preview : 208 gui_split_preview "jd_xtrartistic ${1--2}",${-3--1} 209 210#@gui _ 211# ^ The line above allows to goes 1 level up, so exit the 'Various' folder. 212# Now, the parser considers you are located in the root path of the filter tree. 213# .... You get the idea .... 214 215# A last important note : to be able to test your external filter source, copy it as 216# '$HOME/.gmic' (for Unix-like OS) or '%APPDATA/gmic' (for Windows-like OS). It 217# will be considered as 'local' filter source by the plug-in. Once everything is working 218# fine, you may want to submit your G'MIC filter source to the 'gmic-community' repository 219# (with a pull-request): 220# 221# https://github.com/dtschump/gmic-community/ 222# 223# Thanks for your participation. 224 225 226# Local Variables: 227# mode: sh 228# End: 229# 230# (End of G'MIC custom commands) 231