Implement QuickStart Docs for TinyMS v0.3.1

tinyms-ai · Jan 24, 2022 · f974ffb · f974ffb
1 parent 3d18fd6
commit f974ffb
Show file tree

Hide file tree

Showing 4 changed files with 309 additions and 72 deletions.
diff --git a/docs/en/source/quickstart/install.md b/docs/en/source/quickstart/install.md
@@ -21,9 +21,24 @@ mkdir -pv /root/.pip \
 ```
 
 ```shell
-pip install tinyms==0.3.0
+pip install tinyms==0.3.1
 ```
 
+> Note: There may be some problems during the installation process. The following possible situations are for reference only. If you encounter other problems during the installation process, we welcome you  to submit your issues and pull requests in our [community](https://github.com/tinyms-ai/tinyms), and we will reply you as soon as possible.
+>
+> 1. Error 1: If you use the mirror source to execute the installation command, it may report `Could not find a version that satisfies the requirement tinyms==0.3.1`
+>
+>    **Solution:**
+>
+>    - You can try to use the default official source, directly append `-i https://pypi.python.org/simple/` at the end, the download speed of the default official source may be slower, please be patient :smile:
+>
+> 2. Error 2: If you are a windows user, please make sure that `Microsoft VC++ 14.0` is installed. If not, it may report`ERROR: Microsoft Visual C++ 14.0 or greater is required. Get it with “Microsoft C++ Build Tools” may be reported during the installation process. : https://visualstudio.microsoft.com/visual-cpp-build-tools/`
+>
+>    **Solution:**
+>
+>    - Because TinyMS is dependent on the `Python3.7.5` environment, and Python3 is compiled with `VC++ 14.0`. According to the error prompt, download `Microsoft C++ Build Tools` at the provided [link](https://visualstudio.microsoft.com/visual-cpp-build-tools/) . Note that during the installation process, the two components `windows 10 SDK` and `C++ CMake Tools for Windows` need to be checked in `Desktop Development Module Using C++ Desktop`. For installation details, please refer to [Visual Studio Build Tool Installation](https://devblogs.microsoft.com/cppblog/introducing-the-visual-studio-build-tools/).
+>
+
 ### Docker
 
 For those who don't want to affect the local develop environment due to difficulty of meeting the prerequisites, using [docker](https://www.docker.com/) to install is recommended
@@ -38,17 +53,17 @@ If user wants to experience the image inference service in a visual WEB UI，ple
 * Default version
 
 ```shell
-docker pull tinyms/tinyms:0.3.0
-docker run -it tinyms/tinyms:0.3.0
+docker pull tinyms/tinyms:0.3.1
+docker run -it tinyms/tinyms:0.3.1
 ```
 
 * Jupyter version
 
 If user wants to try jupyter, run the following command line
 
 ```shell
-docker pull tinyms/tinyms:0.1.0-jupyter
-docker run -it --net=host tinyms/tinyms:0.1.0-jupyter
+docker pull tinyms/tinyms:0.3.1-jupyter
+docker run -it --net=host tinyms/tinyms:0.3.1-jupyter
 ```
 
 Open a browser on the local machine, type in
@@ -64,8 +79,8 @@ Example: `188.8.8.88:8888`, the default password is `tinyms`，then user can log
 If user wants to experience the image inference service in a visual WEB UI, run the following command line
 
 ```shell
-docker pull tinyms/tinyms:0.3.0-nginx
-docker run -itd --name=tinyms-nginx -p 80:80 tinyms/tinyms:0.3.0-nginx /bin/bash
+docker pull tinyms/tinyms:0.3.1-nginx
+docker run -itd --name=tinyms-nginx -p 80:80 tinyms/tinyms:0.3.1-nginx /bin/bash
 
 docker exec -it tinyms-nginx /bin/bash
 entrypoint.sh <Your_host_public_IP_address_not_docker_IP_address>

diff --git a/docs/en/source/quickstart/reasoning_visualization_experience.md b/docs/en/source/quickstart/reasoning_visualization_experience.md
@@ -1,6 +1,6 @@
 # TinyMS Reasoning Visualization Experience
 
-Combined with OpenCV image vision library, TinyMS V0.3.0 focus visualization features. Through simple and intuitive image visualization, it helps users to understand the effect of model reasoning more quickly.
+Combined with OpenCV image vision library, TinyMS V0.3.1 focus visualization features. Through simple and intuitive image visualization, it helps users to understand the effect of model reasoning more quickly.
 
 For users who do not want to write code, TinyMS provides a visual interface of WEB UI. Users only need to upload the image to be inferred on the browser page to experience easily. Currently, it supports for `LeNet5`, `CycleGan` and `SSD300` models.
 
@@ -20,38 +20,143 @@ If users need to experience the model reasoning visualization module application
 
 * Static image detection
 
-Note: Please make sure your system has a visual desktop.
+1. Environmental preparation
 
-```script
-# Download the TinyMS project
-git clone https://github.com/tinyms-ai/tinyms.git
-cd tinyms/tests/st/app/object_detection/
-# Run static image detection
-python opencv_image_app.py
-```
+   - An operating system with a visual desktop, such as `Window_x64` or `Ubuntu18.04`
 
-The image to be detected and the image after inference are shown as follows:
+2. Experience the module application
 
-![Input Image](../_static/tinyms_visulization_origin.jpg)
+   ```script
+   # Download the TinyMS project
+   git clone https://github.com/tinyms-ai/tinyms.git
+   cd tinyms/tests/st/app/object_detection/
+   # Run static image detection
+   python opencv_image_app.py
+   ```
 
-![Reasoning Image](../_static/tinyms_visulization_reasoning.jpg)
+   The image to be detected and the image after inference are shown as follows:
+
+   ![Input Image](../_static/tinyms_visulization_origin.jpg)
+
+   ![Reasoning Image](../_static/tinyms_visulization_reasoning.jpg)
 
 * Real-time dynamic detection of video images collected by computer camera
 
-Note: In addition to ensuring that your system has a visual desktop, you also need to have a camera.
-
-If using the container to run code, the camera of the host must be mounted to the container. For example, the host is Ubuntu 18.04 with a camera device and a visual desktop. Perform from step 1 to the final.  If using the host server, perform from step 4 to the final.
-
-```script
-# 1.Install xServer on the host and set permissions
-apt install x11-xserver-utils
-# 2.Allow all users to access the display interface
-xhost +
-# 3.Run container
-docker run -it --rm --device=/dev/video0 -e DISPLAY=unix$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix tinyms/tinyms:0.3.0 /bin/bash
-# 4.Download the TinyMS project in the container
-git clone https://github.com/tinyms-ai/tinyms.git
-cd tinyms/tests/st/app/object_detection/
-# 5.Run dynamic video image detection collected by camera
-python opencv_camera_app.py
-```
+1. Environmental preparation:
+
+   * An operating system with a visual desktop, such as `Window_x64` or `Ubuntu18.04`
+
+   * Make sure the operating system can access the camera normally
+
+     > Note: 
+     >
+     > Generally speaking, for the operating system under the host, such as `Window_x64` and `Ubuntu 18.04`, the camera can be accessed normally, but for the operating system under the virtual machine, please make sure that **the relevant virtual machine services are enabled and the camera driver is connected**. Following, we take the virtual machine `VMware Workstation` under the window as an example:
+     >
+     > 1. First of all, we enter the command `ls /dev/v*` in the terminal  to check whether there is a `/dev/video0` driver. If there is, it means it is normal, please ignore the following operations, if not, we will perform the following operations. 
+     > 2. Secondly, enable the relevant virtual machine services. enable the service `VMware USB Arbitration Service` in the windows host, that is, enter `services.msc` on the keyboard `Win+R` to find the corresponding service and enable it. After it is turned on, the virtual machine needs to be restarted.
+     > 3. Then, connect the camera driver. On the menu bar of `VMware Workstation`, click `Virtual Machine (M)` => `Removable Device` => `Camera Name` => `Host Connection`, and click `Virtual Machine (M)` =>`Settings(S)`=>`USB`, select `USB3.0`.
+     > 4. Finally, You can use `cheese` to test whether the camera can be accessed normally.
+
+2. Experience the module application
+
+   For the different choices for operating systems and different choices for testing methods, we provide the following specific environment experiences, please verify in the corresponding environment, note that **the following environments have all satisfy the two conditions for environmental preparation, which is very important**.
+
+   - If your host operating system is windows 
+
+     - If you test on the host
+
+       **Environmental Requirements:**
+
+       - Operating system：`Window_64`
+
+       - Environmental dependency： `Git` + `Python 3. 7.5` + `TinyMS 0.3.1` + `Microsoft Visual C++ 14.0 or greater`
+
+       - Command line tool：`Git Bash`
+
+         > Note: For details about the environment dependency of VC++ 14.0, please refer to the notes under [Pypi install TinyMS](https://tinyms.readthedocs.io/zh_CN/latest/quickstart/install.html)
+
+       Execute the following commands after the environment requirements are satisfied: 
+
+       ```script
+       # 1.Download the TinyMS project in the container
+       git clone https://github.com/tinyms-ai/tinyms.git
+       cd tinyms/tests/st/app/object_detection/
+       # 2.Run dynamic video image detection collected by camera
+       python opencv_camera_app.py
+       ```
+
+     - If you test on a virtual machine
+
+       Let's take the virtual machine `VMware Workstation` under `Window_x64` as an example. Please refer to the notes in the environment preparation for VM connection to the camera:
+
+       **Environmental Requirements:**
+
+       - Operating system：`Ubuntu18.04 LTS Desktop`
+       - Environmental dependency：  `Docker 18.06.1-ce`
+       - Command line tool：`Terminal`
+
+       Execute the following commands after the environment requirements are satisfied: 
+
+       ```script
+       # 1.Install xServer on the host and set permissions
+       apt install x11-xserver-utils
+       # 2.Allow all users to access the display interface
+       xhost +
+       # 3.Run container
+       docker run -it --rm --device=/dev/video0 -e DISPLAY=unix$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix tinyms/tinyms:0.3.1 /bin/bash
+       # 4.Download the TinyMS project in the container
+       git clone https://github.com/tinyms-ai/tinyms.git
+       cd tinyms/tests/st/app/object_detection/
+       # 5.Run dynamic video image detection collected by camera
+       python opencv_camera_app.py
+       ```
+
+   - If your host operating system is ubuntu
+
+     - If you test on the host
+
+       **Environmental Requirements:**
+
+       - Operating system：`Ubuntu 18.04 LTS Desktop`
+     
+       - Environmental dependency： `Git` + `Python 3. 7.5` + `TinyMS 0.3.1`
+     
+       - Command line tool：`Terminal`
+     
+       Execute the following commands after the environment requirements are satisfied: 
+     
+       ```script
+       # 1.Download the TinyMS project in the container
+       git clone https://github.com/tinyms-ai/tinyms.git
+       cd tinyms/tests/st/app/object_detection/
+       # 2.Run dynamic video image detection collected by camera
+       python opencv_camera_app.py
+       ```
+     
+     - If you use docker access
+
+       **Environmental Requirements:**
+
+       - Operating system：`Ubuntu18.04 LTS Desktop`
+       
+       - Environmental dependency：  `Docker 18.06.1-ce`
+       
+       - Command line tool：`Terminal`
+       
+       Execute the following commands after the environment requirements are satisfied: 
+       
+       ```script
+       # 1.Install xServer on the host and set permissions
+       apt install x11-xserver-utils
+       # 2.Allow all users to access the display interface
+       xhost +
+       # 3.Run container
+       docker run -it --rm --device=/dev/video0 -e DISPLAY=unix$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix tinyms/tinyms:0.3.1 /bin/bash
+       # 4.Download the TinyMS project in the container
+       git clone https://github.com/tinyms-ai/tinyms.git
+       cd tinyms/tests/st/app/object_detection/
+       # 5.Run dynamic video image detection collected by camera
+       python opencv_camera_app.py
+       ```
+   
+   Currently, the document is still being improved:smile:. If your environment is not in the above reference, after you try it, you still have problems, we sincerely invite you to submit your issues and pull requests in our [community](https://github.com/tinyms-ai/tinyms), and we will reply you as soon as possible.
diff --git a/docs/zh_CN/source/quickstart/install.md b/docs/zh_CN/source/quickstart/install.md
@@ -9,6 +9,7 @@
 环境要求
 
 - OS: `Ubuntu 18.04` or `Windows 10`
+
 - Python: `3.7.5`
 
 中国国内用户可以运行以下代码配置国内镜像源，解决下载速度慢的问题
@@ -21,9 +22,23 @@ mkdir -pv /root/.pip \
 ```
 
 ```shell
-pip install tinyms==0.3.0
+pip install tinyms==0.3.1
 ```
 
+> 注：在执行过程中可能会出现一些问题，以下可能情况仅供参考。在安装过程中你可能会碰到其它问题，我们欢迎你在我们的[社区](https://github.com/tinyms-ai/tinyms)，提出您的Issues和Pull requests，我们会及时回复您。
+>
+> 1. Error 1：若使用镜像源执行安装命令可能会报 `Could not find a version that satisfies the requirement tinyms==0.3.1`
+>
+>    **解决方案：**
+>
+>    - 可以试试使用默认官方源，直接在末尾追加`-i https://pypi.python.org/simple/`，采用默认官方源下载速度可能较慢，请耐心等待:smile:
+>
+> 2. Error 2：如果是windows用户请确保是否安装了`Microsoft VC++ 14.0`，若没有，安装过程中可能会报`ERROR：Microsoft Visual C++ 14.0 or greater is required.Get it with “Microsoft C++ Build  Tools”: https://visualstudio.microsoft.com/visual-cpp-build-tools/`
+>
+>    **解决方案：**
+>
+>    - 因为TinyMS是对`Python3.7.5`环境依赖的，而Python3是通过`VC++ 14.0`编译的。我们可以根据错误提示，在提供的[链接](https://visualstudio.microsoft.com/visual-cpp-build-tools/ )下载`Microsoft C++ Build Tools`，注意在安装过程中需在`使用C++桌面的桌面开发模块`勾选`windows 10 SDK`和`用于Windows的C++ CMake工具`俩个组件，相关安装详情可以参考[Visual studio 生成工具安装]( https://docs.microsoft.com/zh-cn/archive/blogs/c/visual-studio-%E7%94%9F%E6%88%90%E5%B7%A5%E5%85%B7%E4%BB%8B%E7%BB%8D)。
+
 ### Docker
 
 对于不想改变本地环境设置的用户，推荐使用 [docker](https://www.docker.com/) 进行安装
@@ -37,17 +52,17 @@ pip install tinyms==0.3.0
 * 普通版本
 
 ```shell
-docker pull tinyms/tinyms:0.3.0
-docker run -it tinyms/tinyms:0.3.0
+docker pull tinyms/tinyms:0.3.1
+docker run -it tinyms/tinyms:0.3.1
 ```
 
 * Jupyter版本
 
 如果想体验jupyter教程，运行下列命令行
 
 ```shell
-docker pull tinyms/tinyms:0.1.0-jupyter
-docker run -it --net=host tinyms/tinyms:0.1.0-jupyter
+docker pull tinyms/tinyms:0.3.1-jupyter
+docker run -it --net=host tinyms/tinyms:0.3.1-jupyter
 ```
 
 在本地打开浏览器，输入
@@ -63,8 +78,8 @@ docker run -it --net=host tinyms/tinyms:0.1.0-jupyter
 如果想在可视化WEB界面体验图片推理服务，运行下列命令行
 
 ```shell
-docker pull tinyms/tinyms:0.3.0-nginx
-docker run -itd --name=tinyms-nginx -p 80:80 tinyms/tinyms:0.3.0-nginx /bin/bash
+docker pull tinyms/tinyms:0.3.1-nginx
+docker run -itd --name=tinyms-nginx -p 80:80 tinyms/tinyms:0.3.1-nginx /bin/bash
 
 docker exec -it tinyms-nginx /bin/bash
 entrypoint.sh <容器所在宿主机的公网IP地址>