Docs: new preprocess docs and usage docs for readme (tensorspace-team…

…#227)

README.md

@@ -59,9 +59,9 @@ By applying TensorSpace API, it is more intuitive to visualize and understand an
 <b>Fig. 2</b> - TensorSpace Workflow
 </p>
 
-### 1. Install TensorSpace Library
+### 1. Install TensorSpace
 
-**Basic Case**
+#### Install in the Basic Case
 
 - Step 1: Download Dependencies
 
@@ -88,7 +88,7 @@ Include all build files in web page.
 <script src="tensorspace.min.js"></script>
 ```
 
-**Using TensorSpace in Progressive Framework**
+#### Install in the Progressive Framework
 
 - Step 1: Install TensorSpace
 
@@ -112,28 +112,38 @@ import * as TSP from 'tensorspace';
 
 Checkout this [Angular example](https://github.com/tensorspace-team/tensorspace/tree/master/examples/helloworld-angular) for more information.
 
-### 2. Preprocess Pre-trained Model
+### 2. Preprocess the Pre-trained Model
 
-For presenting multiple intermediate outputs, we need to [preprocess](https://github.com/tensorspace-team/tensorspace/tree/master/docs/preprocess) the pre-trained model.
+Before applying TensorSpace to visualize the pre-trained model, there is an important pipeline - TensorSpace model preprocessing ( Checkout [this article](https://tensorspace.org/html/docs/preIntro.html) for more information about TensorSpace preprocessing ). We can use [TensorSpace Converter](https://github.com/tensorspace-team/tensorspace-converter) to quickly complete the TensorSpace Preprocessing.
 
-Based on different training libraries, we provide different tutorials: [TensorFlow model preprocessing](https://github.com/tensorspace-team/tensorspace/tree/master/docs/preprocess/TensorFlow), [Keras model preprocessing](https://github.com/tensorspace-team/tensorspace/tree/master/docs/preprocess/Keras) and [TensorFlow.js model preprocessing](https://github.com/tensorspace-team/tensorspace/tree/master/docs/preprocess/TensorFlowJS).
+For example, if we have a [tf.keras model](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/rawModel) in hand, we can use the following TensorSpace-Converter conversion script to convert a tf.keras model to the TensorSpace compatible format:
+```shell
+$ tensorspacejs_converter \
+    --input_model_from="tensorflow" \
+    --input_model_format="tf_keras" \
+    --output_layer_names="padding_1,conv_1,maxpool_1,conv_2,maxpool_2,dense_1,dense_2,softmax" \
+    ./PATH/TO/MODEL/tf_keras_model.h5 \
+    ./PATH/TO/SAVE/DIR
+```
 
+**Note:**
 
-### 3. Create 3D TensorSpoace Model
+* Make sure to install `tensorspacejs` pip package, and setup a TensorSpace-Converter runtime environment before using TensorSpace-Converter to preprocess the pre-trained model.
+* Checkout [TensorSpace-Converter Repo](https://github.com/tensorspace-team/tensorspace-converter) for more information about TensorSpace-Converter.
 
-If TensorSpace is installed successfully and the pre-trained deep learning model is preprocessed, let's create an interactive 3D TensorSpace model.
+### 3. Using TensorSpace to Visualize the Model
 
-For convenience, feel free to use the resources from our [HelloWorld](https://github.com/tensorspace-team/tensorspace/tree/master/examples/helloworld) directory.
+If TensorSpace is installed successfully and the pre-trained deep learning model is preprocessed, let's create an interactive 3D TensorSpace model.
 
-We will use the [preprocessed TensorSpace compatible LeNet model](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/model) and [sample input data ("5")](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/data/5.json) as an example to illustrate this step. All source code can be found in [helloworld.html](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/helloworld.html).
+For convenience, we will use the the resources from this repository's [HelloWorld](https://github.com/tensorspace-team/tensorspace/tree/master/examples/helloworld) directory, which includes [preprocessed TensorSpace compatible LeNet model](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/convertedModel) and [sample input data ("5")](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/data/5.json) as an example to illustrate this step. All source code can be found in [helloworld.html](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/helloworld.html).
 
 First, we need to new a TensorSpace model instance:
 ```JavaScript
 let container = document.getElementById( "container" );
 let model = new TSP.models.Sequential( container );
 ```
 
-Next, based on the LeNet structure: Input + 2 X (Conv2D & Maxpooling) + 3 X (Dense), we build the structure of the model:
+Next, based on the LeNet structure: Input + Padding2D + 2 X (Conv2D & Maxpooling) + 3 X (Dense), build the Topology of the TensorSpace model:
 ```JavaScript
 model.add( new TSP.layers.GreyscaleInput() );
 model.add( new TSP.layers.Padding2d() );
@@ -148,18 +158,18 @@ model.add( new TSP.layers.Output1d({
 }) );
 ```
 
-Last, we should load our [preprocessed TensorSpace compatible model](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/model/mnist.json) and use `init()` method to create the TensorSpace model:
+Last, we should load our [preprocessed TensorSpace compatible model](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/convertedModel) and use `init()` method to create the TensorSpace model:
 ```JavaScript
 model.load({
-    type: "tfjs",
-    url: './lenetModel/mnist.json'
+    type: "tensorflow",
+    url: './PATH/TO/MODEL/model.json'
 });
 model.init(function(){
     console.log("Hello World from TensorSpace!");
 });
 ```
 
-We can get the following Fig. 2 model in the browser if everything looks good.
+We can get the following Fig. 3 model in the browser if everything looks good.
 
 <p align="center">
 <img width="100%" src="https://raw.githack.com/tensorspace-team/tensorspace/master/assets/HelloWorld_empty_lenet.jpg">

README_zh.md

@@ -19,7 +19,7 @@
 </p>
 
 TensorSpace是一套用于构建神经网络3D可视化应用的框架。
-开发者可以使用类Keras风格的TensorSpace API，轻松创建可视化网络、加载神经网络模型并在浏览器中基于已加载的模型进行3D可交互呈现。
+开发者可以使用 TensorSpace API，轻松创建可视化网络、加载神经网络模型并在浏览器中基于已加载的模型进行3D可交互呈现。
 TensorSpace可以使您更直观地观察神经网络模型，并了解该模型是如何通过中间层 tensor 的运算来得出最终结果的。
 TensorSpace 支持3D可视化经过适当预处理之后的 TensorFlow、Keras、TensorFlow.js 模型。
 
@@ -46,7 +46,7 @@ TensorSpace 支持3D可视化经过适当预处理之后的 TensorFlow、Keras
 
 TensorSpace 基于 TensorFlow.js、Three.js 和 Tween.js 开发，用于对神经网络进行3D可视化呈现。通过使用 TensorSpace，不仅仅能展示神经网络的结构，还可以呈现网络的内部特征提取、中间层的数据交互以及最终的结果预测等一系列过程。
 
-通过使用 TensorSpace，可以帮助您更直观地观察并理解基于TensorFlow、Keras或者TensorFlow.js开发的神经网络模型。
+通过使用 TensorSpace，可以帮助您更直观地观察、理解、展示基于 TensorFlow、Keras 或者 TensorFlow.js 开发的神经网络模型。
 TensorSpace 降低了前端开发者进行深度学习相关应用开发的门槛。
 我们期待看到更多基于 TensorSpace 开发的3D可视化应用。
 
@@ -65,9 +65,9 @@ TensorSpace 降低了前端开发者进行深度学习相关应用开发的门
 <b>图2</b> - TensorSpace 使用流程
 </p>
 
-### 安装
+### 1. 安装
 
-**基本使用场景**
+#### 基本使用场景下安装
 
 - 第一步：下载依赖库
 
@@ -92,7 +92,7 @@ TensorSpace 降低了前端开发者进行深度学习相关应用开发的门
 <script src="tensorspace.min.js"></script>
 ```
 
-**在渐进式框架中使用 TensorSpace**
+#### 在渐进式框架中安装
 
 - 第一步： 安装 TensorSpace
 
@@ -116,27 +116,38 @@ import * as TSP from 'tensorspace';
 
 这个 [Angular 样例](https://github.com/tensorspace-team/tensorspace/tree/master/examples/helloworld-angular) 具体展示了如何使用。
 
-### 模型预处理
+### 2. 模型预处理
 
-为了获得神经网络中间层的运算结果，我们需要对已有的模型进行[模型预处理](https://github.com/tensorspace-team/tensorspace/tree/master/docs/preprocess_zh)。
+在应用 TensorSpace 可视化之前，需要完成一个重要的步骤————对预训练模型进行预处理（通过 [这篇介绍](https://tensorspace.org/html/docs/preIntro_zh.html) 可以了解更多有关 TensorSpace 预处理的概念与原理）。[TensorSpace-Converter](https://github.com/tensorspace-team/tensorspace-converter) 可以帮助开发者快速完成 TensorSpace 预处理过程的辅助工具。
 
-基于不同的机器学习库，我们提供了 [TensorFlow 模型预处理教程](https://github.com/tensorspace-team/tensorspace/tree/master/docs/preprocess_zh/TensorFlow)、[Keras 模型预处理教程](https://github.com/tensorspace-team/tensorspace/tree/master/docs/preprocess_zh/Keras) 以及 [TensorFlow.js 模型预处理教程](https://github.com/tensorspace-team/tensorspace/tree/master/docs/preprocess_zh/TensorFlowJS)。
+举个例子，如果现在有一个 [tf.keras model](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/rawModel) 的模型，我们可以使用以下 TensorSpace-Converter 转化脚本快速将 tf.keras 模型转化成 TensorSpace 兼容的格式：
+```shell
+$ tensorspacejs_converter \
+    --input_model_from="tensorflow" \
+    --input_model_format="tf_keras" \
+    --output_layer_names="padding_1,conv_1,maxpool_1,conv_2,maxpool_2,dense_1,dense_2,softmax" \
+    ./PATH/TO/MODEL/tf_keras_model.h5 \
+    ./PATH/TO/SAVE/DIR
+```
 
-### 使用
+**注意：**
 
-在成功安装完成 TensorSpace 并完成神经网络模型预处理之后，我们可以来创建一个3D TensorSpace 模型。
+* 在使用 TensorSpace-Converter 对预训练的模型进行预处理之前，需要下载 `tensorspacejs` 的 pip 包，并且配置 TensorSpace-Converter 的运行环境。
+* 查看 [TensorSpace-Converter 仓库](https://github.com/tensorspace-team/tensorspace-converter) 了解更多有关 TensorSpace-Converter 的使用细节。
 
-为了简化步骤，请随意使用我们在 [HelloWorld](https://github.com/tensorspace-team/tensorspace/tree/master/examples/helloworld) 路径下所提供的资源。
+### 3. 使用 TensorSpace 可视化模型
+
+在成功安装完成 TensorSpace 并完成神经网络模型预处理之后，我们可以来创建一个3D TensorSpace 模型。
 
-我们将会用到[适配 TensorSpace 的预处理模型](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/model) 以及[样例输入数据（“5”）](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/data/5.json)作为使用样例来进行说明。所有的源码都可以在 [helloworld.html](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/helloworld.html) 文件中找到。
+我们将使用 [HelloWorld](https://github.com/tensorspace-team/tensorspace/tree/master/examples/helloworld) 路径下的资源，其中包括[适配 TensorSpace 的预处理模型](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/convertedModel) 以及[样例输入数据（“5”）](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/data/5.json)作为使用样例来进行说明。所有的源码都可以在 [helloworld.html](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/helloworld.html) 文件中找到。
 
 首先，我们需要新建一个 TensorSpace 模型实例：
 ```JavaScript
 let container = document.getElementById( "container" );
 let model = new TSP.models.Sequential( container );
 ```
 
-然后，基于 LeNet 网络的结构：输入层 + 2 X (Conv2D层 & Maxpooling层) + 3 X (Dense层)，我们可以搭建其模型结构：
+然后，基于 LeNet 网络的结构：输入层 + Padding2d层 + 2 X (Conv2D层 & Maxpooling层) + 3 X (Dense层)，我们可以搭建其模型结构：
 ```JavaScript
 model.add( new TSP.layers.GreyscaleInput() );
 model.add( new TSP.layers.Padding2d() );
@@ -151,11 +162,11 @@ model.add( new TSP.layers.Output1d({
 }) );
 ```
 
-最后，我们需要载入[经过预处理的 TensorSpace 适配模型](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/model/mnist.json)并使用`init()`方法来创建模型对象：
+最后，我们需要载入[经过预处理的 TensorSpace 适配模型](https://github.com/tensorspace-team/tensorspace/blob/master/examples/helloworld/convertedModel)并使用`init()`方法来创建模型对象：
 ```JavaScript
 model.load({
-    type: "tfjs",
-    url: './lenetModel/mnist.json'
+    type: "tensorflow",
+    url: './PATH/TO/MODEL/model.json'
 });
 model.init(function(){
     console.log("Hello World from TensorSpace!");

examples/helloworld/convert.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+tensorspacejs_converter \
+    --input_model_from="tensorflow" \
+    --input_model_format="tf_keras" \
+    --output_layer_names="conv_1,maxpool_1,conv_2,maxpool_2,dense_1,dense_2,softmax" \
+    ./rawModel/tf_keras_model.h5 \
+    ./convertedModel

examples/helloworld/convertedModel/model.json

@@ -0,0 +1 @@
+{"modelTopology": {"keras_version": "2.1.6-tf", "backend": "tensorflow", "model_config": {"class_name": "Model", "config": {"name": "model", "layers": [{"name": "reshape_1_input", "class_name": "InputLayer", "config": {"batch_input_shape": [null, 28, 28], "dtype": "float32", "sparse": false, "name": "reshape_1_input"}, "inbound_nodes": []}, {"name": "reshape_1", "class_name": "Reshape", "config": {"name": "reshape_1", "trainable": true, "batch_input_shape": [null, 28, 28], "dtype": "float32", "target_shape": [28, 28, 1]}, "inbound_nodes": [[["reshape_1_input", 0, 0, {}]]]}, {"name": "padding_1", "class_name": "ZeroPadding2D", "config": {"name": "padding_1", "trainable": true, "dtype": "float32", "padding": [[2, 2], [2, 2]], "data_format": "channels_last"}, "inbound_nodes": [[["reshape_1", 0, 0, {}]]]}, {"name": "conv_1", "class_name": "Conv2D", "config": {"name": "conv_1", "trainable": true, "dtype": "float32", "filters": 6, "kernel_size": [5, 5], "strides": [1, 1], "padding": "valid", "data_format": "channels_last", "dilation_rate": [1, 1], "activation": "linear", "use_bias": true, "kernel_initializer": {"class_name": "GlorotUniform", "config": {"seed": null, "dtype": "float32"}}, "bias_initializer": {"class_name": "Zeros", "config": {"dtype": "float32"}}, "kernel_regularizer": null, "bias_regularizer": null, "activity_regularizer": null, "kernel_constraint": null, "bias_constraint": null}, "inbound_nodes": [[["padding_1", 0, 0, {}]]]}, {"name": "maxpool_1", "class_name": "MaxPooling2D", "config": {"name": "maxpool_1", "trainable": true, "dtype": "float32", "pool_size": [2, 2], "padding": "valid", "strides": [2, 2], "data_format": "channels_last"}, "inbound_nodes": [[["conv_1", 0, 0, {}]]]}, {"name": "conv_2", "class_name": "Conv2D", "config": {"name": "conv_2", "trainable": true, "dtype": "float32", "filters": 16, "kernel_size": [5, 5], "strides": [1, 1], "padding": "valid", "data_format": "channels_last", "dilation_rate": [1, 1], "activation": "linear", "use_bias": true, "kernel_initializer": {"class_name": "GlorotUniform", "config": {"seed": null, "dtype": "float32"}}, "bias_initializer": {"class_name": "Zeros", "config": {"dtype": "float32"}}, "kernel_regularizer": null, "bias_regularizer": null, "activity_regularizer": null, "kernel_constraint": null, "bias_constraint": null}, "inbound_nodes": [[["maxpool_1", 0, 0, {}]]]}, {"name": "maxpool_2", "class_name": "MaxPooling2D", "config": {"name": "maxpool_2", "trainable": true, "dtype": "float32", "pool_size": [2, 2], "padding": "valid", "strides": [2, 2], "data_format": "channels_last"}, "inbound_nodes": [[["conv_2", 0, 0, {}]]]}, {"name": "flatten", "class_name": "Flatten", "config": {"name": "flatten", "trainable": true, "dtype": "float32", "data_format": "channels_last"}, "inbound_nodes": [[["maxpool_2", 0, 0, {}]]]}, {"name": "dense_1", "class_name": "Dense", "config": {"name": "dense_1", "trainable": true, "dtype": "float32", "units": 120, "activation": "relu", "use_bias": true, "kernel_initializer": {"class_name": "GlorotUniform", "config": {"seed": null, "dtype": "float32"}}, "bias_initializer": {"class_name": "Zeros", "config": {"dtype": "float32"}}, "kernel_regularizer": null, "bias_regularizer": null, "activity_regularizer": null, "kernel_constraint": null, "bias_constraint": null}, "inbound_nodes": [[["flatten", 0, 0, {}]]]}, {"name": "dense_2", "class_name": "Dense", "config": {"name": "dense_2", "trainable": true, "dtype": "float32", "units": 84, "activation": "relu", "use_bias": true, "kernel_initializer": {"class_name": "GlorotUniform", "config": {"seed": null, "dtype": "float32"}}, "bias_initializer": {"class_name": "Zeros", "config": {"dtype": "float32"}}, "kernel_regularizer": null, "bias_regularizer": null, "activity_regularizer": null, "kernel_constraint": null, "bias_constraint": null}, "inbound_nodes": [[["dense_1", 0, 0, {}]]]}, {"name": "softmax", "class_name": "Dense", "config": {"name": "softmax", "trainable": true, "dtype": "float32", "units": 10, "activation": "softmax", "use_bias": true, "kernel_initializer": {"class_name": "GlorotUniform", "config": {"seed": null, "dtype": "float32"}}, "bias_initializer": {"class_name": "Zeros", "config": {"dtype": "float32"}}, "kernel_regularizer": null, "bias_regularizer": null, "activity_regularizer": null, "kernel_constraint": null, "bias_constraint": null}, "inbound_nodes": [[["dense_2", 0, 0, {}]]]}], "input_layers": [["reshape_1_input", 0, 0]], "output_layers": [["padding_1", 0, 0], ["conv_1", 0, 0], ["maxpool_1", 0, 0], ["conv_2", 0, 0], ["maxpool_2", 0, 0], ["dense_1", 0, 0], ["dense_2", 0, 0], ["softmax", 0, 0]]}}, "training_config": {"optimizer_config": {"class_name": "Adam", "config": {"lr": 0.0010000000474974513, "beta_1": 0.8999999761581421, "beta_2": 0.9990000128746033, "decay": 0.0, "epsilon": 1e-07, "amsgrad": false}}, "loss": "sparse_categorical_crossentropy", "metrics": ["accuracy"], "weighted_metrics": null, "sample_weight_mode": null, "loss_weights": null}}, "weightsManifest": [{"paths": ["group1-shard1of1"], "weights": [{"name": "conv_1/kernel", "shape": [5, 5, 1, 6], "dtype": "float32"}, {"name": "conv_1/bias", "shape": [6], "dtype": "float32"}, {"name": "conv_2/kernel", "shape": [5, 5, 6, 16], "dtype": "float32"}, {"name": "conv_2/bias", "shape": [16], "dtype": "float32"}, {"name": "dense_1/kernel", "shape": [400, 120], "dtype": "float32"}, {"name": "dense_1/bias", "shape": [120], "dtype": "float32"}, {"name": "dense_2/kernel", "shape": [120, 84], "dtype": "float32"}, {"name": "dense_2/bias", "shape": [84], "dtype": "float32"}, {"name": "softmax/kernel", "shape": [84, 10], "dtype": "float32"}, {"name": "softmax/bias", "shape": [10], "dtype": "float32"}]}]}

examples/helloworld/helloworld.html

@@ -7,10 +7,9 @@
 
     <script src="../lib/three.min.js"></script>
     <script src="../lib/tween.min.js"></script>
-		<!-- <script src="../lib/stats.min.js"></script> -->
     <script src="../lib/tf.min.js"></script>
     <script src="../lib/TrackballControls.js"></script>
-    <script src="../../dist/tensorspace.js"></script>
+    <script src="../../dist/tensorspace.min.js"></script>
 
     <script src="../lib/jquery.min.js"></script>
 
@@ -27,6 +26,7 @@
             width: 100%;
             height: 100%;
         }
+
     </style>
 
 </head>
@@ -54,11 +54,8 @@
 		}) );
 
 		model.load({
-			type: "tfjs",
-			url: './model/mnist.json',
-			onComplete: function() {
-				console.log( "\"Hello World!\" from TensorSpace Loader." );
-			}
+			type: "tensorflow",
+			url: './convertedModel/model.json'
 		});
 		model.init( function() {