From 2771ff4b87623ef7305932ff6385beae5081c617 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20M=C3=B6nig?= <jens@moenig.org>
Date: Mon, 8 Jan 2024 10:20:44 +0100
Subject: [PATCH] added graphic filter effects (matrix-kernel convolution
 tools) to the pixels library

---
 HISTORY.md                 | 6 +++++-
 libraries/pixel_module.xml | 2 +-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/HISTORY.md b/HISTORY.md
index 91135847f0..c277552dd7 100755
--- a/HISTORY.md
+++ b/HISTORY.md
@@ -1,6 +1,9 @@
 # Snap! (BYOB) History
 
 ## in development:
+* **New Features:**
+    * (better) matrix-kernel convolution support, automatic zero-padding
+    * new graphic filter effects tools in the pixels library
 * **Notable Changes:**
     * hyperized ITEM OF
     * tweaked hyperDyadic() to zip matching atoms based on comparing their dimensions backwards (as in NumPy)
@@ -11,7 +14,8 @@
     * fixed speech balloons inside ASK menus
 
 2024-01-08
-* threads: tweaked hyperDyadic() to allow explicit dimension matching 
+* threads: tweaked hyperDyadic() to allow explicit dimension matching
+* pixels library: added graphic filter effects (matrix-kernel convolutions)
 
 2024-01-05
 * objects: fixed speech balloons inside ASK menus
diff --git a/libraries/pixel_module.xml b/libraries/pixel_module.xml
index 0156888544..cf394bc3c5 100644
--- a/libraries/pixel_module.xml
+++ b/libraries/pixel_module.xml
@@ -1 +1 @@
-<blocks app="Snap! 7, https://snap.berkeley.edu" version="2"><block-definition s="$camera snap" type="reporter" category="sensing"><comment x="0" y="0" w="216" collapsed="false">takes a snapshot with the webcam and reports it as a new costume, or zero if the user cancels</comment><header></header><code></code><translations>pt:$camera a imagem actual do vídeo&#xD;</translations><inputs></inputs><script><block s="doDeclareVariables"><list><l>callback</l><l>pic</l></list></block><block s="doSetVar"><l>callback</l><block s="reportApplyExtension"><l>mda_snap</l><list></list></block></block><block s="doWaitUntil"><block s="evaluate"><block s="reifyScript"><script><block s="doSetVar"><l>pic</l><block s="evaluate"><block var="callback"/><list></list></block></block><block s="doReport"><block s="reportNot"><block s="reportEquals"><block var="pic"/><block s="reportBoolean"><l><bool>false</bool></l></block></block></block></block></script><list></list></block><list></list></block></block><block s="doReport"><block var="pic"/></block></script></block-definition><block-definition s="export costume %&apos;costume&apos;" type="command" category="looks"><header></header><code></code><translations></translations><inputs><input type="%s" readonly="true"><options>§_costumesMenu</options></input></inputs><script><block s="doSetVar"><l>costume</l><block s="reportIfElse"><block s="reportIsA"><block var="costume"/><l><option>costume</option></l></block><block var="costume"/><block s="reportFindFirst"><block s="reifyPredicate"><autolambda><block s="reportEquals"><block s="reportGetImageAttribute"><l><option>name</option></l><l></l></block><block var="costume"/></block></autolambda><list></list></block><block s="reportGet"><l><option>costumes</option></l></block></block></block></block><block s="doIf"><block s="reportIsA"><block var="costume"/><l><option>costume</option></l></block><script><block s="doApplyExtension"><l>cst_export(cst, name)</l><list><block var="costume"/><l></l></list></block></script></block></script></block-definition><block-definition s="set name of costume %&apos;costume&apos; to %&apos;name&apos;" type="command" category="looks"><header></header><code></code><translations></translations><inputs><input type="%s" readonly="true"><options>§_costumesMenu</options></input><input type="%s">thing</input></inputs><script><block s="doSetVar"><l>costume</l><block s="reportIfElse"><block s="reportIsA"><block var="costume"/><l><option>costume</option></l></block><block var="costume"/><block s="reportFindFirst"><block s="reifyPredicate"><autolambda><block s="reportEquals"><block s="reportGetImageAttribute"><l><option>name</option></l><l></l></block><block var="costume"/></block></autolambda><list></list></block><block s="reportGet"><l><option>costumes</option></l></block></block></block></block><block s="doIf"><block s="reportIsA"><block var="costume"/><l><option>costume</option></l></block><script><block s="doApplyExtension"><l>obj_name(obj, name)</l><list><block var="costume"/><block var="name"/></list></block></script></block></script></block-definition><block-definition s="export costume list %&apos;costumes&apos; base name %&apos;name&apos;" type="command" category="looks"><header></header><code></code><translations></translations><inputs><input type="%l"></input><input type="%s">frame</input></inputs><script><block s="doDeclareVariables"><list><l>count</l></list></block><block s="doSetVar"><l>count</l><block s="reportListAttribute"><l><option>length</option></l><block var="costumes"/></block></block><block s="doForEach"><l>item</l><block s="reportListAttribute"><l><option>reverse</option></l><block var="costumes"/></block><script><block s="doApplyExtension"><l>cst_export(cst, name)</l><list><block var="item"/><block s="reportJoinWords"><list><block var="name"/><l> (</l><block var="count"/><l>)</l></list></block></list></block><block s="doChangeVar"><l>count</l><l>-1</l></block><block s="doIf"><block s="reportEquals"><block s="reportModulus"><block var="count"/><l>10</l></block><l>0</l></block><script><block s="doWait"><l>1</l></block></script></block></script></block></script></block-definition></blocks>
\ No newline at end of file
+<blocks app="Snap! 9.0, https://snap.berkeley.edu" version="2"><block-definition s="$camera snap" type="reporter" category="sensing"><comment x="0" y="0" w="216" collapsed="false">takes a snapshot with the webcam and reports it as a new costume, or zero if the user cancels</comment><header></header><code></code><translations>pt:$camera a imagem actual do vídeo&#xD;</translations><inputs></inputs><script><block s="doDeclareVariables"><list><l>callback</l><l>pic</l></list></block><block s="doSetVar"><l>callback</l><block s="reportApplyExtension"><l>mda_snap</l><list></list></block></block><block s="doWaitUntil"><block s="evaluate"><block s="reifyScript"><script><block s="doSetVar"><l>pic</l><block s="evaluate"><block var="callback"/><list></list></block></block><block s="doReport"><block s="reportNot"><block s="reportVariadicEquals"><list><block var="pic"/><block s="reportBoolean"><l><bool>false</bool></l></block></list></block></block></block></script><list></list></block><list></list></block></block><block s="doReport"><block var="pic"/></block></script></block-definition><block-definition s="export costume %&apos;costume&apos;" type="command" category="looks"><header></header><code></code><translations></translations><inputs><input type="%s" readonly="true"><options>§_costumesMenu</options></input></inputs><script><block s="doSetVar"><l>costume</l><block s="reportIfElse"><block s="reportIsA"><block var="costume"/><l><option>costume</option></l></block><block var="costume"/><block s="reportFindFirst"><block s="reifyPredicate"><autolambda><block s="reportVariadicEquals"><list><block s="reportGetImageAttribute"><l><option>name</option></l><l></l></block><block var="costume"/></list></block></autolambda><list></list></block><block s="reportGet"><l><option>costumes</option></l></block></block></block></block><block s="doIf"><block s="reportIsA"><block var="costume"/><l><option>costume</option></l></block><script><block s="doApplyExtension"><l>cst_export(cst, name)</l><list><block var="costume"/><l></l></list></block></script><list></list></block></script></block-definition><block-definition s="set name of costume %&apos;costume&apos; to %&apos;name&apos;" type="command" category="looks"><header></header><code></code><translations></translations><inputs><input type="%s" readonly="true"><options>§_costumesMenu</options></input><input type="%s">thing</input></inputs><script><block s="doSetVar"><l>costume</l><block s="reportIfElse"><block s="reportIsA"><block var="costume"/><l><option>costume</option></l></block><block var="costume"/><block s="reportFindFirst"><block s="reifyPredicate"><autolambda><block s="reportVariadicEquals"><list><block s="reportGetImageAttribute"><l><option>name</option></l><l></l></block><block var="costume"/></list></block></autolambda><list></list></block><block s="reportGet"><l><option>costumes</option></l></block></block></block></block><block s="doIf"><block s="reportIsA"><block var="costume"/><l><option>costume</option></l></block><script><block s="doApplyExtension"><l>obj_name(obj, name)</l><list><block var="costume"/><block var="name"/></list></block></script><list></list></block></script></block-definition><block-definition s="export costume list %&apos;costumes&apos; base name %&apos;name&apos;" type="command" category="looks"><header></header><code></code><translations></translations><inputs><input type="%l"></input><input type="%s">frame</input></inputs><script><block s="doDeclareVariables"><list><l>count</l></list></block><block s="doSetVar"><l>count</l><block s="reportListAttribute"><l><option>length</option></l><block var="costumes"/></block></block><block s="doForEach"><l>item</l><block s="reportListAttribute"><l><option>reverse</option></l><block var="costumes"/></block><script><block s="doApplyExtension"><l>cst_export(cst, name)</l><list><block var="item"/><block s="reportJoinWords"><list><block var="name"/><l> (</l><block var="count"/><l>)</l></list></block></list></block><block s="doChangeVar"><l>count</l><l>-1</l></block><block s="doIf"><block s="reportVariadicEquals"><list><block s="reportModulus"><block var="count"/><l>10</l></block><l>0</l></list></block><script><block s="doWait"><l>1</l></block></script><list></list></block></script></block></script></block-definition><block-definition s="%&apos;filter&apos; filter on %&apos;costume&apos;" type="reporter" category="looks"><header></header><code></code><translations></translations><inputs><input type="%s" readonly="true">Blur<options>Blur&#xD;Sharpen&#xD;Outline&#xD;Emboss&#xD;Edge</options></input><input type="%s" readonly="true">current<options>§_costumesMenu</options></input></inputs><script><block s="doDeclareVariables"><list><l>kernel</l><l>pixels</l><l>channels</l><l>w</l><l>h</l></list></block><block s="doSetVar"><l>kernel</l><block s="reportIfElse"><block s="reportVariadicGreaterThan"><list><block s="reportListAttribute"><l><option>rank</option></l><block var="filter"/></block><l>1</l></list></block><block var="filter"/><custom-block s="filter %s"><block var="filter"/></custom-block></block></block><block s="doSetVar"><l>pixels</l><block s="reportGetImageAttribute"><l><option>pixels</option></l><block var="costume"/></block></block><block s="doIf"><block s="reportListContainsItem"><block s="reportNewList"><list><l>outline</l><l>emboss</l><l>edge</l></list></block><block var="filter"/></block><script><block s="doSetVar"><l>channels</l><l>3</l></block><block s="doSetVar"><l>pixels</l><block s="reportVariadicProduct"><list><block var="pixels"/><block s="reportNewList"><list><l>1</l><l>1</l><l>1</l></list></block></list></block><comment w="137" collapsed="true">remove alpha channel</comment></block></script><list><l><bool>true</bool></l><script><block s="doSetVar"><l>channels</l><l>4</l></block></script></list></block><block s="doSetVar"><l>w</l><block s="reportGetImageAttribute"><l><option>width</option></l><block var="costume"/></block></block><block s="doSetVar"><l>h</l><block s="reportGetImageAttribute"><l><option>height</option></l><block var="costume"/></block></block><block s="doReport"><block s="reportNewCostume"><block s="reportReshape"><custom-block s="convolve matrix %l * kernel %l"><block s="reportReshape"><block var="pixels"/><list><block var="h"/><block var="w"/><block var="channels"/></list></block><block var="kernel"/></custom-block><list><l></l><block var="channels"/></list></block><block var="w"/><block var="h"/></block></block></script></block-definition><block-definition s="filter %&apos;name&apos;" type="reporter" category="looks"><header></header><code></code><translations></translations><inputs><input type="%s" readonly="true">Blur<options>Blur&#xD;Sharpen&#xD;Outline&#xD;Emboss&#xD;Edge</options></input></inputs><script><block s="doIf"><block s="reportVariadicEquals"><list><block var="name"/><l>sharpen</l></list></block><script><block s="doReport"><custom-block s="kernel %br %n %n %n %br %n %n %n %br %n %n %n"><l>0</l><l>-1</l><l>0</l><l>-1</l><l>5</l><l>-1</l><l>0</l><l>-1</l><l>0</l></custom-block></block></script><list><block s="reportVariadicEquals"><list><block var="name"/><l>outline</l></list></block><script><block s="doReport"><custom-block s="kernel %br %n %n %n %br %n %n %n %br %n %n %n"><l>-1</l><l>-1</l><l>-1</l><l>-1</l><l>8</l><l>-1</l><l>-1</l><l>-1</l><l>-1</l></custom-block></block></script><block s="reportVariadicEquals"><list><block var="name"/><l>emboss</l></list></block><script><block s="doReport"><custom-block s="kernel %br %n %n %n %br %n %n %n %br %n %n %n"><l>-2</l><l>-1</l><l>0</l><l>-1</l><l>1</l><l>1</l><l>0</l><l>1</l><l>2</l></custom-block></block></script><block s="reportVariadicEquals"><list><block var="name"/><l>edge</l></list></block><script><block s="doReport"><custom-block s="kernel %br %n %n %n %br %n %n %n %br %n %n %n"><l>-1</l><l>0</l><l>1</l><l>-2</l><l>0</l><l>2</l><l>-1</l><l>0</l><l>1</l></custom-block></block></script></list></block><block s="doReport"><custom-block s="kernel %br %n %n %n %br %n %n %n %br %n %n %n"><l>0.0625</l><l>0.125</l><l>0.0625</l><l>0.125</l><l>0.25</l><l>0.125</l><l>0.0625</l><l>0.125</l><l>0.0625</l></custom-block></block></script></block-definition><block-definition s="kernel $nl %&apos;a1&apos; %&apos;b1&apos; %&apos;c1&apos; $nl %&apos;a2&apos; %&apos;b2&apos; %&apos;c2&apos; $nl %&apos;a3&apos; %&apos;b3&apos; %&apos;c3&apos;" type="reporter" category="lists"><header></header><code></code><translations></translations><inputs><input type="%n"></input><input type="%n"></input><input type="%n"></input><input type="%n"></input><input type="%n"></input><input type="%n"></input><input type="%n"></input><input type="%n"></input><input type="%n"></input></inputs><script><block s="doReport"><block s="reportNewList"><list><block s="reportNewList"><list><block var="a1"/><block var="b1"/><block var="c1"/></list></block><block s="reportNewList"><list><block var="a2"/><block var="b2"/><block var="c2"/></list></block><block s="reportNewList"><list><block var="a3"/><block var="b3"/><block var="c3"/></list></block></list></block></block></script></block-definition><block-definition s="convolve matrix %&apos;matrix&apos; * kernel %&apos;kernel&apos;" type="reporter" category="operators"><header></header><code></code><translations></translations><inputs><input type="%l"></input><input type="%l"></input></inputs><script><block s="doDeclareVariables"><list><l>channels</l><l>every coordinate</l><l>padding</l></list></block><block s="doSetVar"><l>padding</l><block s="reportQuotient"><block s="reportDifference"><block s="reportListItem"><block s="reportNewList"><list><l>1</l><l>2</l></list></block><block s="reportListAttribute"><l><option>dimensions</option></l><block var="kernel"/></block></block><l>1</l></block><l>2</l></block><comment w="119" collapsed="false">assume odd dimensions, typically 3x3 or 5x5</comment></block><block s="doSetVar"><l>channels</l><block s="reportListItem"><l>3</l><block s="reportListAttribute"><l><option>dimensions</option></l><block var="matrix"/></block></block></block><block s="doIf"><block s="reportVariadicAnd"><list><block s="reportVariadicGreaterThan"><list><block var="channels"/><l>0</l></list></block><block s="reportVariadicLessThan"><list><block s="reportListAttribute"><l><option>dimensions</option></l><block var="kernel"/></block><l>3</l></list></block></list></block><script><block s="doSetVar"><l>kernel</l><block s="reportReshape"><custom-block s="stretch %l by %n"><block s="reportListAttribute"><l><option>flatten</option></l><block var="kernel"/></block><block var="channels"/></custom-block><block s="reportConcatenatedLists"><list><block s="reportListAttribute"><l><option>dimensions</option></l><block var="kernel"/></block><block s="reportNewList"><list><block var="channels"/></list></block></list></block></block></block></script><list></list><comment w="90" collapsed="false">reshape the kernel to match the input matrix&apos;s channels, if any</comment></block><block s="doSetVar"><l>every coordinate</l><block s="reportCrossproduct"><block s="reportNumbers"><l>1</l><block s="reportListItem"><block s="reportNewList"><list><l>1</l><l>2</l></list></block><block s="reportListAttribute"><l><option>dimensions</option></l><block var="matrix"/></block></block></block></block></block><block s="doReport"><block s="reportReshape"><block s="reportVariadicSum"><block s="reportListAttribute"><l><option>columns</option></l><block s="reportVariadicSum"><block s="reportListAttribute"><l><option>columns</option></l><block s="reportVariadicProduct"><list><block s="reportListItem"><block s="reportNumbers"><block s="reportDifference"><block var="every coordinate"/><block var="padding"/></block><block s="reportVariadicSum"><list><block var="every coordinate"/><block var="padding"/></list></block></block><block var="matrix"/></block><block var="kernel"/></list></block></block></block></block></block><block s="reportListAttribute"><l><option>dimensions</option></l><block var="matrix"/></block><comment w="80" collapsed="false">for every padded pixel create a partial copy of the input, item-multiply it with the kernel and take its overall sum (∑)</comment></block></block></script></block-definition><block-definition s="stretch %&apos;data&apos; by %&apos;factor&apos;" type="reporter" category="lists"><header></header><code></code><translations></translations><inputs><input type="%l"></input><input type="%n"></input></inputs><script><block s="doReport"><block s="reportListItem"><block s="reportMonadic"><l><option>ceiling</option></l><block s="reportQuotient"><block s="reportNumbers"><l>1</l><block s="reportVariadicProduct"><list><block s="reportListAttribute"><l><option>length</option></l><block var="data"/></block><block var="factor"/></list></block></block><block var="factor"/></block></block><block var="data"/></block></block></script></block-definition></blocks>
\ No newline at end of file