Update documentation

openvinotoolkit · Aug 9, 2024 · ad797b1 · ad797b1
1 parent c8a3f43
commit ad797b1
Show file tree

Hide file tree

Showing 9 changed files with 298 additions and 35 deletions.
diff --git a/develop/_modules/openvino_xai/explainer/explanation.html b/develop/_modules/openvino_xai/explainer/explanation.html
@@ -535,21 +535,58 @@ <h1>Source code for openvino_xai.explainer.explanation</h1><div class="highlight
 
 <div class="viewcode-block" id="Explanation.save">
 <a class="viewcode-back" href="../../../api-manual.html#openvino_xai.explainer.Explanation.save">[docs]</a>
-    <span class="k">def</span> <span class="nf">save</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">dir_path</span><span class="p">:</span> <span class="n">Path</span> <span class="o">|</span> <span class="nb">str</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
-<span class="w">        </span><span class="sd">&quot;&quot;&quot;Dumps saliency map.&quot;&quot;&quot;</span>
+    <span class="k">def</span> <span class="nf">save</span><span class="p">(</span>
+        <span class="bp">self</span><span class="p">,</span>
+        <span class="n">dir_path</span><span class="p">:</span> <span class="n">Path</span> <span class="o">|</span> <span class="nb">str</span><span class="p">,</span>
+        <span class="n">prefix</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
+        <span class="n">postfix</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span><span class="p">,</span>
+        <span class="n">confidence_scores</span><span class="p">:</span> <span class="n">Dict</span><span class="p">[</span><span class="nb">int</span><span class="p">,</span> <span class="nb">float</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="p">)</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
+<span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">        Dumps saliency map images to the specified directory.</span>
+
+<span class="sd">        Allows flexibly name the files with the prefix and postfix.</span>
+<span class="sd">        {prefix} + target_id + {postfix}.jpg</span>
+
+<span class="sd">        Also allows to add confidence scores to the file names.</span>
+<span class="sd">        {prefix} + target_id + {postfix} + confidence.jpg</span>
+
+<span class="sd">        save(output_dir) -&gt; aeroplane.jpg</span>
+<span class="sd">        save(output_dir, prefix=&quot;image_name_target_&quot;) -&gt; image_name_target_aeroplane.jpg</span>
+<span class="sd">        save(output_dir, postfix=&quot;_class_map&quot;) -&gt; aeroplane_class_map.jpg</span>
+<span class="sd">        save(</span>
+<span class="sd">            output_dir, prefix=&quot;image_name_&quot;, postfix=&quot;_conf_&quot;, confidence_scores=scores</span>
+<span class="sd">        ) -&gt; image_name_aeroplane_conf_0.85.jpg</span>
+
+<span class="sd">        Parameters:</span>
+<span class="sd">            :param dir_path: The directory path where the saliency maps will be saved.</span>
+<span class="sd">            :type dir_path: Path | str</span>
+<span class="sd">            :param prefix: Optional prefix for the saliency map names. Default is an empty string.</span>
+<span class="sd">            :type prefix: str</span>
+<span class="sd">            :param postfix: Optional postfix for the saliency map names. Default is an empty string.</span>
+<span class="sd">            :type postfix: str</span>
+<span class="sd">            :param confidence_scores: Dict with confidence scores for each class index. Default is None.</span>
+<span class="sd">            :type confidence_scores: Dict[int, float] | None</span>
+
+<span class="sd">        &quot;&quot;&quot;</span>
+
         <span class="n">os</span><span class="o">.</span><span class="n">makedirs</span><span class="p">(</span><span class="n">dir_path</span><span class="p">,</span> <span class="n">exist_ok</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-        <span class="n">save_name</span> <span class="o">=</span> <span class="n">name</span> <span class="k">if</span> <span class="n">name</span> <span class="k">else</span> <span class="s2">&quot;&quot;</span>
-        <span class="k">for</span> <span class="n">cls_idx</span><span class="p">,</span> <span class="n">map_to_save</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_saliency_map</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
+
+        <span class="n">template</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">prefix</span><span class="si">}</span><span class="se">{{</span><span class="s2">target_name</span><span class="se">}}</span><span class="si">{</span><span class="n">postfix</span><span class="si">}</span><span class="se">{{</span><span class="s2">conf_score</span><span class="se">}}</span><span class="s2">.jpg&quot;</span>
+        <span class="k">for</span> <span class="n">target_idx</span><span class="p">,</span> <span class="n">map_to_save</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_saliency_map</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
+            <span class="n">conf_score</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
             <span class="n">map_to_save</span> <span class="o">=</span> <span class="n">cv2</span><span class="o">.</span><span class="n">cvtColor</span><span class="p">(</span><span class="n">map_to_save</span><span class="p">,</span> <span class="n">code</span><span class="o">=</span><span class="n">cv2</span><span class="o">.</span><span class="n">COLOR_RGB2BGR</span><span class="p">)</span>
-            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">cls_idx</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>
-                <span class="n">cv2</span><span class="o">.</span><span class="n">imwrite</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">dir_path</span><span class="p">,</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">save_name</span><span class="si">}</span><span class="s2">.jpg&quot;</span><span class="p">),</span> <span class="n">img</span><span class="o">=</span><span class="n">map_to_save</span><span class="p">)</span>
-                <span class="k">return</span>
+            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">target_idx</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>
+                <span class="n">target_name</span> <span class="o">=</span> <span class="s2">&quot;activation_map&quot;</span>
+            <span class="k">elif</span> <span class="bp">self</span><span class="o">.</span><span class="n">label_names</span> <span class="ow">and</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">target_idx</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">int64</span><span class="p">):</span>
+                <span class="n">target_name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">label_names</span><span class="p">[</span><span class="n">target_idx</span><span class="p">]</span>
             <span class="k">else</span><span class="p">:</span>
-                <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">label_names</span><span class="p">:</span>
-                    <span class="n">target_name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">label_names</span><span class="p">[</span><span class="n">cls_idx</span><span class="p">]</span>
-                <span class="k">else</span><span class="p">:</span>
-                    <span class="n">target_name</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">cls_idx</span><span class="p">)</span>
-            <span class="n">image_name</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">save_name</span><span class="si">}</span><span class="s2">_target_</span><span class="si">{</span><span class="n">target_name</span><span class="si">}</span><span class="s2">.jpg&quot;</span> <span class="k">if</span> <span class="n">save_name</span> <span class="k">else</span> <span class="sa">f</span><span class="s2">&quot;target_</span><span class="si">{</span><span class="n">target_name</span><span class="si">}</span><span class="s2">.jpg&quot;</span>
+                <span class="n">target_name</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">target_idx</span><span class="p">)</span>
+
+            <span class="k">if</span> <span class="n">confidence_scores</span> <span class="ow">and</span> <span class="n">target_idx</span> <span class="ow">in</span> <span class="n">confidence_scores</span><span class="p">:</span>
+                <span class="n">conf_score</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="n">confidence_scores</span><span class="p">[</span><span class="nb">int</span><span class="p">(</span><span class="n">target_idx</span><span class="p">)]</span><span class="si">:</span><span class="s2">.2f</span><span class="si">}</span><span class="s2">&quot;</span>
+
+            <span class="n">image_name</span> <span class="o">=</span> <span class="n">template</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">target_name</span><span class="o">=</span><span class="n">target_name</span><span class="p">,</span> <span class="n">conf_score</span><span class="o">=</span><span class="n">conf_score</span><span class="p">)</span>
             <span class="n">cv2</span><span class="o">.</span><span class="n">imwrite</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">dir_path</span><span class="p">,</span> <span class="n">image_name</span><span class="p">),</span> <span class="n">img</span><span class="o">=</span><span class="n">map_to_save</span><span class="p">)</span></div>
 
 

diff --git a/develop/_modules/openvino_xai/methods/black_box/aise.html b/develop/_modules/openvino_xai/methods/black_box/aise.html
@@ -400,11 +400,10 @@ <h1>Source code for openvino_xai.methods.black_box.aise</h1><div class="highligh
 
 <span class="kn">import</span> <span class="nn">collections</span>
 <span class="kn">import</span> <span class="nn">math</span>
-<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Callable</span><span class="p">,</span> <span class="n">Dict</span><span class="p">,</span> <span class="n">List</span><span class="p">,</span> <span class="n">Tuple</span>
+<span class="kn">from</span> <span class="nn">typing</span> <span class="kn">import</span> <span class="n">Callable</span><span class="p">,</span> <span class="n">Dict</span><span class="p">,</span> <span class="n">List</span><span class="p">,</span> <span class="n">Mapping</span><span class="p">,</span> <span class="n">Tuple</span>
 
 <span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
 <span class="kn">import</span> <span class="nn">openvino.runtime</span> <span class="k">as</span> <span class="nn">ov</span>
-<span class="kn">from</span> <span class="nn">openvino.runtime.utils.data_helpers.wrappers</span> <span class="kn">import</span> <span class="n">OVDict</span>
 <span class="kn">from</span> <span class="nn">scipy.optimize</span> <span class="kn">import</span> <span class="n">Bounds</span><span class="p">,</span> <span class="n">direct</span>
 
 <span class="kn">from</span> <span class="nn">openvino_xai.common.utils</span> <span class="kn">import</span> <span class="p">(</span>
@@ -427,7 +426,7 @@ <h1>Source code for openvino_xai.methods.black_box.aise</h1><div class="highligh
 <span class="sd">    :param model: OpenVINO model.</span>
 <span class="sd">    :type model: ov.Model</span>
 <span class="sd">    :param postprocess_fn: Post-processing function that extract scores from IR model output.</span>
-<span class="sd">    :type postprocess_fn: Callable[[OVDict], np.ndarray]</span>
+<span class="sd">    :type postprocess_fn: Callable[[Mapping], np.ndarray]</span>
 <span class="sd">    :param preprocess_fn: Pre-processing function, identity function by default</span>
 <span class="sd">        (assume input images are already preprocessed by user).</span>
 <span class="sd">    :type preprocess_fn: Callable[[np.ndarray], np.ndarray]</span>
@@ -440,7 +439,7 @@ <h1>Source code for openvino_xai.methods.black_box.aise</h1><div class="highligh
     <span class="k">def</span> <span class="fm">__init__</span><span class="p">(</span>
         <span class="bp">self</span><span class="p">,</span>
         <span class="n">model</span><span class="p">:</span> <span class="n">ov</span><span class="o">.</span><span class="n">Model</span><span class="p">,</span>
-        <span class="n">postprocess_fn</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="n">OVDict</span><span class="p">],</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">],</span>
+        <span class="n">postprocess_fn</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="n">Mapping</span><span class="p">],</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">],</span>
         <span class="n">preprocess_fn</span><span class="p">:</span> <span class="n">Callable</span><span class="p">[[</span><span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">],</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">]</span> <span class="o">=</span> <span class="n">IdentityPreprocessFN</span><span class="p">(),</span>
         <span class="n">device_name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;CPU&quot;</span><span class="p">,</span>
         <span class="n">prepare_model</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">,</span>

diff --git a/develop/_modules/openvino_xai/methods/black_box/rise.html b/develop/_modules/openvino_xai/methods/black_box/rise.html
@@ -419,7 +419,7 @@ <h1>Source code for openvino_xai.methods.black_box.rise</h1><div class="highligh
 <span class="sd">    :param model: OpenVINO model.</span>
 <span class="sd">    :type model: ov.Model</span>
 <span class="sd">    :param postprocess_fn: Post-processing function that extract scores from IR model output.</span>
-<span class="sd">    :type postprocess_fn: Callable[[OVDict], np.ndarray]</span>
+<span class="sd">    :type postprocess_fn: Callable[[Mapping], np.ndarray]</span>
 <span class="sd">    :param preprocess_fn: Pre-processing function, identity function by default</span>
 <span class="sd">        (assume input images are already preprocessed by user).</span>
 <span class="sd">    :type preprocess_fn: Callable[[np.ndarray], np.ndarray]</span>