From 624f6c6f22d7b6ca4d03704153c2809db192bfec Mon Sep 17 00:00:00 2001 From: sylnsfar Date: Sun, 11 Sep 2016 19:46:53 +0800 Subject: [PATCH] updated README and added a Chinese version --- README-cn.md | 291 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 238 ++++++++++++++++++++++------------------- 2 files changed, 420 insertions(+), 109 deletions(-) create mode 100644 README-cn.md diff --git a/README-cn.md b/README-cn.md new file mode 100644 index 0000000..d380c36 --- /dev/null +++ b/README-cn.md @@ -0,0 +1,291 @@ +# QR-Code +[*back to English*](https://github.com/sylnsfar/qrcode/blob/master/README.md) + +* **更新 (160906)**: 新增 **exe** 版本 - [myqr.exe in qrcode_win](https://github.com/sylnsfar/qrcode_win) + +* **更新 (160908)**: 新增**网页**版本 - [amazing-qrcode](http://www.amazing-qrcode.com/) *(made by [Maras0830](https://github.com/Maras0830))* + +* **更新 (160910)**: 发布到 **PyPI** - [**MyQR**](https://pypi.python.org/pypi/MyQR) ! + + * 160911: 更新为可导入的模块 + + ​ + +## 概述 + +**Python 二维码生成器** + +可生成*普通二维码*、*带图片的艺术二维码（黑白与彩色）*、*动态二维码（黑白与彩色）*。 + +​ + +​ + +## Contents 目录 + +* [概述](#概述) +* [目录](#目录) +* [示例](#示例) +* [安装](#安装) +* [使用方法](#使用方法) + * [命令行方式](#命令行方式) + * [作为导入文件](#作为导入文件) +* [使用提示](#使用提示) +* [可用字符](#可用字符) +* [依赖库](#依赖库) +* [运行环境](#运行环境) +* [协议](#协议) + + +​ + +## 示例 + +![](https://github.com/sylnsfar/qrcode/blob/master/example/qrs0.jpg) + +![](https://github.com/sylnsfar/qrcode/blob/master/example/qrs1.jpg) + +![](https://github.com/sylnsfar/qrcode/blob/master/example/qrs2.jpg) + +![](https://github.com/sylnsfar/qrcode/blob/master/example/c_qrcode.gif)![](https://github.com/sylnsfar/qrcode/blob/master/example/daftpunktocat-guy_qrcode.gif) + +![](https://github.com/sylnsfar/qrcode/blob/master/example/zootopia_qrcode.gif)![](https://github.com/sylnsfar/qrcode/blob/master/example/daftpunktocat-guy_qrcode0.gif) + + + + + +## 安装 + +```python +# via pip +pip(3) install myqr(or MyQR) +``` + +​ + + + +## 使用方法 + +### 命令行方式 + +*（**提示**：如果你尚未安装 [**MyQR**](https://pypi.python.org/pypi/MyQR) ，以下内容请使用`python(3) myqr.py` 而非`myqr` 。）* + +```python +# 概括 +myqr Words + [-v {1,2,3,...,40}] + [-l {L,M,Q,H}] + [-n output-filename] + [-d output-directory] + [-p picture_file] + [-c] + [-con contrast] + [-bri brightness] +``` + +- [普通二维码](#普通二维码) 介绍了 `Words`, `-v`, `-l`, `-n`, `-d` +- [艺术二维码](#艺术二维码) 介绍了 `-p`, `-c`, `-con`, `-bri` +- [动态GIF二维码](#动态gif二维码) 介绍了动态的生成方法和注意点 + + + + + +#### 普通二维码 + +![](https://github.com/sylnsfar/qrcode/blob/master/example/0.png) + +```markdown +#1 Words +myqr https://github.com +``` + +* 在命令后输入链接或者句子作为参数，然后在程序的当前目录中产生相应的二维码图片文件，默认命名为” qrcode.png“。 + + ​ + +```markdown +#2 -v, -l +myqr https://github.com -v 10 -l Q +``` + +* **默认边长**是取决于你输入的信息的长度和使用的纠错等级； + + 而**默认纠错等级**是最高级的H。 + +* **自定义**：如果想要控制边长和纠错水平就使用 `-v` 和 `-l` 参数。 + + `-v` 控制边长，范围是**1至40**，数字越大边长越大； + + `-l` 控制纠错水平，范围是**L、M、Q、H**，从左到右依次升高。 + + + + +```markdown +#3 -n, -d +myqr https://github.com -n github_qr.jpg -d .../paths/ +``` + +- **默认输出文件名**是“ qrcode.png "，而**默认存储位置**是当前目录。 + +- 自定义：可以自己定义输出名称和位置。**注意**同名文件会覆盖旧的。 + + `-n` 控制文件名，格式可以是 `.jpg`， `.png` ，`.bmp` ，`.gif` ； + + `-d` 控制位置。 + + ​ + + + + + + +#### 艺术二维码 + +![](https://github.com/sylnsfar/qrcode/blob/master/example/1.png)![](https://github.com/sylnsfar/qrcode/blob/master/example/2.png) + + +```markdown +#1 -p +myqr https://github.com -p github.jpg +``` + +* 参数`-p` 用来将QR二维码图像与一张同目录下的图片相结合，产生一张**黑白**图片。 + + ​ + + + + +```markdown +#2 -c +myqr https://github.com -p github.jpg -c +``` + +* 加上参数 `-c` 可以使产生的图片由黑白变为**彩色**的。 + + ​ + + + +```markdown +#3 -con, -bri +myqr https://github.com -p github.jpg [-c] -con 1.5 -bri 1.6 +``` + +* 参数`-con` 用以调节图片的**对比度**，1.0 表示原始图片，更小的值表示更低对比度，更大反之。**默认为1.0**。 + +* 参数 `-bri` 用来调节图片的**亮度**，其余用法和取值与 `-con` 相同。 + + + + +#### 动态GIF二维码 + +![](https://github.com/sylnsfar/qrcode/blob/master/example/daftpunktocat-guy_qrcode.gif)![](https://github.com/sylnsfar/qrcode/blob/master/example/daftpunktocat-guy_qrcode0.gif) + +动态二维码与上述的带图片的二维码的生成方法没什么区别，你只要采用 `.gif` 格式的图片即可生成黑白或者彩色的动态二维码。但**注意**如果使用了 `-n` 参数自定义输出的文件名，切记其格式也必须是 `.gif` 格式。 + + + +### 作为导入文件 + +```python +# 安装模块后 +from MyQR import myqr +version, level, qr_name = myqr.run( + words, + version=1, + level='H', + picture=None, + colorized=False, + contrast=1.0, + brightness=1.0, + save_name=None, + save_dir=os.getcwd() + ) +``` + + + +*一下各个参数以及在[上文](#命令行方式)有所介绍* + + +```python +# help(myqr) +Positional parameter + words: str + +Optional parameters + version: int, from 1 to 40 + level: str, just one of ('L','M','Q','H') + picutre: str, a filename of a image + colorized: bool + constrast: float + brightness: float + save_name: str, the output filename like 'example.png' + save_dir: str, the output directory +``` + + + + + +## 使用提示 + +* 请采用**正方形**或近似正方形的图片 + +* 建议在图片尺寸大的时候使用 `-v` 的值也应该**适当**变大。 + +* 如果图片有透明无色部分，最终效果是：![](https://github.com/sylnsfar/qrcode/blob/master/example/aa.png) + + 你可以将透明部分修改成白色，最终效果会变成![](https://github.com/sylnsfar/qrcode/blob/master/example/a0.png) + + + + +## 可用字符 + +* 数字 0 到 9 + +* 大小写的英文字母 + +* 常用**英文标点符号**和空格 + + ```console + · , . : ; + - * / \ ~ ! @ # $ % ^ & ` [ ] ( ) ? _ { } | and (space) + ``` + + +​ + +## 依赖库 + +* [pillow](https://pypi.python.org/pypi/Pillow/3.3.1) +* [numpy](https://pypi.python.org/pypi/numpy) +* [imageio](https://pypi.python.org/pypi/imageio) + + + + +*（**提示**：如果没有安装 [**MyQR**](https://pypi.python.org/pypi/MyQR) ，使用命令`pip install -r requirements.txt` 来安装所有依赖的库。）* + + + +## 运行环境 + +* Linux, Python 3 +* Windows, Python 3 +* Mac, Python 3 + + +​ + + +## 协议 + +* GPLv3 \ No newline at end of file diff --git a/README.md b/README.md index cf0d919..3469211 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,44 @@ # QR-Code +[*转到中文版*](https://github.com/sylnsfar/qrcode/blob/master/README-cn.md) + * **update (160906)**: added an **exe** version - [myqr.exe in qrcode_win](https://github.com/sylnsfar/qrcode_win) * **update (160908)**: added a **web** version - [amazing-qrcode](http://www.amazing-qrcode.com/) *(made by [Maras0830](https://github.com/Maras0830))* -* **update (160910)**: distributed to **PyPI** - [**MyQR**](https://pypi.python.org/pypi/MyQR/1.0.0) ! +* **update (160910)**: distributed to **PyPI** - [**MyQR**](https://pypi.python.org/pypi/MyQR) ! + + * 160911: updated to be importable ​ -## Overview 概述 +## Overview -**QR Code in Python** +**Python QR Code Generator** -It can generate common qr-code, artistic qr-code (black & white or colorized), animated qr-code (black & white or colorized). - -**Python 二维码生成器** - -可以生成普通二维码、带图片的艺术二维码（黑白与彩色）、动态二维码（黑白与彩色）。 +Generate *common qr-code*, *artistic qr-code (black & white or colorized)*, *animated qr-code (black & white or colorized)*. ​ -​ +## Contents -## Contents 目录 - -* [Overview 概述](#overview-概述) -* [Contents 目录](#contents-目录) -* [Example 示例](#example-示例) -* [Install 安装](#install-安装) -* [Usage 用法](#usage-用法) - * [Common QR-Code 普通QR二维码](#common-qr-code-普通qr二维码) - * [Artistic QR-Code 艺术QR二维码](#artistic-qr-code-艺术qr二维码) - * [Animated GIF QR-Code 动态二维码](#animated-gif-qr-code-动态二维码) -* [Tips 提示](#tips-提示) -* [Supported Characters 可用字符](#supported-characters-可用字符) -* [Dependencies 依赖库](#dependencies-依赖库) -* [Environment 运行环境](#environment-运行环境) -* [License 协议](#license-协议) +* [Overview](#overview) +* [Contents](#contents) +* [Examples](#examples) +* [Install](#install) +* [Usage](#usage) + * [Terminal Way](#terminal-way) + * [Import Way](#import-way) +* [Tips](#tips) +* [Supported Characters](#supported-characters) +* [Dependencies](#dependencies) +* [Environment](#environment) +* [License](#license) ​ -## Example 示例 +## Examples ![](https://github.com/sylnsfar/qrcode/blob/master/example/qrs0.jpg) @@ -57,7 +54,7 @@ It can generate common qr-code, artistic qr-code (black & white or co -## Install 安装 +## Install ```python # via pip @@ -68,40 +65,43 @@ pip(3) install myqr(or MyQR) -## Usage 用法 +## Usage -(**TIPS**: If you haven't install [**MyQR**](https://pypi.python.org/pypi/MyQR/1.0.0), you should `python(3) myqr.py` instead of `myqr` blow.) +### Terminal Way -（**提示**：如果你尚未安装 [**MyQR**](https://pypi.python.org/pypi/MyQR/1.0.0) ，以下内容请使用`python(3) myqr.py` 而非`myqr` 。） +*(**TIPS**: If you haven't install [**MyQR**](https://pypi.python.org/pypi/MyQR), you should `python(3) myqr.py` instead of `myqr` blow.)* + +```python +# summary +myqr Words + [-v {1,2,3,...,40}] + [-l {L,M,Q,H}] + [-n output-filename] + [-d output-directory] + [-p picture_file] + [-c] + [-con contrast] + [-bri brightness] +``` + +- see [Common QR-Code](#common-qr-code) for `Words`, `-v`, `-l`, `-n`, `-d` +- see [Artistic QR-Code](#artistic-qr-code) for `-p`, `-c`, `-con`, `-bri` +- see [Animated GIF QR-Code](#animated-gif-qr-code) about GIF +​ -### Common QR-Code 普通QR二维码 + +#### Common QR-Code ![](https://github.com/sylnsfar/qrcode/blob/master/example/0.png) -``` -myqr [-h] - [-v {1,2,3,...,40}] - [-l {L,M,Q,H}] - Words -``` - -* Use argument `-h` for help. - - 使用参数 `-h` 来获得使用帮助。 - - ​ - - ```markdown -#1 url +#1 Words myqr https://github.com ``` -* **Simplest way**: Just input a URL or a sentence, then get your QR-Code in the current directory. - - **最简单的用法**：在命令后输入链接或者句子作为参数，然后在程序的当前目录中产生相应的QR二维码图片。 +* Just input a URL or a sentence, then get your QR-Code named 'qrcode.png' in the current directory. ​ @@ -110,47 +110,47 @@ myqr https://github.com myqr https://github.com -v 10 -l Q ``` -* The **default** length of a side of QR-Code depends both on the numbers of words you input and the level. And the **default** level (Error Correction Level) is **H** (the highest). +* The **default** size of QR-Code depends both on the numbers of words you input and the level, while the **default** level (Error Correction Level) is **H** (the highest). - **默认边长**是取决于你输入的信息的长度和使用的纠错等级；而**默认纠错等级**是最高级的H。 +* **Customize**: If you want to control the size and the error-correction-level, use the `-v` and `-l` arguments. -* **Customize size**: If you want to control the length and the error-correction-level, use the `-v` and `-l` arguments. The `-v` representing the length is from a minimum of 1 to a maximum of 40. The `-l` representing the error correction level is one of L, M, Q and H, where L is the lowest level and H is the highest. + `-v` representing the length is from a minimum of **1** to a maximum of **40**. - **自定义尺寸**：如果想要控制边长和纠错水平就使用 `-v` 和 `-l` 参数。使用 `-v` 来控制边长，范围是1至40，数字越大边长越大；使用 `-l` 来控制纠错水平，范围是L、M、Q、H，从左到右依次升高。 - - ​ + `-l` representing the error correction level is one of **L, M, Q and H**, where L is the lowest level and H is the highest. -### Artistic QR-Code 艺术QR二维码 + + +```markdown +#3 -n, -d +myqr https://github.com -n github_qr.jpg -d .../paths/ +``` + +* The **default** output-filename is 'qrcode.png', while the **default** output-directory is current directory. + +* **Customize**: You can name the output-file and decide the output-directory. **Notice** that if the name is as same as a existing file, the old one will be deleted. + + `-n` representing the output-filename could be in the format one of `.jpg`， `.png` ，`.bmp` ，`.gif` . + + `-d` means directory. + + + + + + +#### Artistic QR-Code ![](https://github.com/sylnsfar/qrcode/blob/master/example/1.png)![](https://github.com/sylnsfar/qrcode/blob/master/example/2.png) - myqr [-h] - [-v {1,2,3,...,40}] - [-l {L,M,Q,H}] - [-p picture_file] - [-c] - [-con contrast] - [-bri brightness] - Words -* arguments `-h`, `-v` and `-l` is as mentioned above. - - 参数 `-h`, `-v` 和 `-l` 如上文述。 - - ​ - - ```markdown #1 -p myqr https://github.com -p github.jpg ``` -* The `-p` is to combine the QR-Code with the following picture which is in the same directory as the program. The resulting picture is **black and white** by default. +* The `-p` is to combine the QR-Code with the following picture which is in the same directory as the program. The resulting picture is **black and white** by default. - 参数`-p` 用来将QR二维码图像与一张同目录下的图片相结合，产生一张**黑白**图片。 - - ​ @@ -162,8 +162,6 @@ myqr https://github.com -p github.jpg -c * The `-c` is to make the resulting picture **colorized**. - 加上参数 `-c` 可以使产生的图片由黑白变为**彩色**的。 - ​ @@ -175,63 +173,87 @@ myqr https://github.com -p github.jpg [-c] -con 1.5 -bri 1.6 * The `-con` flag changes the **contrast** of the picture - a low number corresponds to low contrast and a high number to high contrast. **Default: 1.0**. - 参数`-con` 用以调节图片的**对比度**，1.0 表示原始图片，更小的值表示更低对比度，更大反之。**默认为1.0**。 - * The `-bri` flag changes the **brightness** and the parameter values work the same as those for `-con`. **Default: 1.0**. - 参数 `-bri` 用来调节图片的**亮度**，其余用法和取值与 `-con` 相同。 -​ - - -### Animated GIF QR-Code 动态二维码 +#### Animated GIF QR-Code ![](https://github.com/sylnsfar/qrcode/blob/master/example/daftpunktocat-guy_qrcode.gif)![](https://github.com/sylnsfar/qrcode/blob/master/example/daftpunktocat-guy_qrcode0.gif) -The only difference from Artistic QR-Code mentioned above is that you should input an image file in the `.gif` format. The you can get your black-and-white or colorful qr-code. +The only difference from Artistic QR-Code mentioned above is that you should input an image file in the `.gif` format. The you can get your black-and-white or colorful qr-code. Remember that when you use `-n` to customize the output-filename, then the output-filename must end by `.gif`. -动态二维码与上述的带图片的二维码的生成方法没什么区别，你只要采用 `.gif` 格式的图片即可黑白或者彩色的动态二维码。 -​ -## Tips 提示 +### Import Way + +```python +# after installation +from MyQR import myqr +version, level, qr_name = myqr.run( + words, + version=1, + level='H', + picture=None, + colorized=False, + contrast=1.0, + brightness=1.0, + save_name=None, + save_dir=os.getcwd() + ) +``` + + +*details about each parameter are as mentioned [above](#terminal-way)* + + +```python +# help(myqr) +Positional parameter + words: str + +Optional parameters + version: int, from 1 to 40 + level: str, just one of ('L','M','Q','H') + picutre: str, a filename of a image + colorized: bool + constrast: float + brightness: float + save_name: str, the output filename like 'example.png' + save_dir: str, the output directory +``` + + + + + + + + +## Tips * Use a nearly **square** picture instead of a rectangle one. - 请采用**正方形**或近似正方形的图片 - -* If the size of the picture is large, you should also choose a rightly large `-v` instead of using the default one. - - 建议在图片尺寸大的时候使用 `-v` 的值也应该适当变大。 +* If the size of the picture is large, you should also choose a **rightly** large `-v` instead of using the default one. * If part of the picture is transparent, the qr code will look like: ![](https://github.com/sylnsfar/qrcode/blob/master/example/aa.png) You can change the transparent layer to white, and then it will look like: ![](https://github.com/sylnsfar/qrcode/blob/master/example/a0.png) - 如果图片有透明无色部分，最终效果是：![](https://github.com/sylnsfar/qrcode/blob/master/example/aa.png) - - 你可以将透明部分修改成白色，最终效果会变成![](https://github.com/sylnsfar/qrcode/blob/master/example/a0.png) -​ -## Supported Characters 可用字符 + +## Supported Characters * Numbers: `0~9` - 数字 0 到 9 - * Letters: `a~z, A~Z` - 大小写的英文字母 - * Common punctuations: - 常用**英文标点符号**和空格 - ```console · , . : ; + - * / \ ~ ! @ # $ % ^ & ` [ ] ( ) ? _ { } | and (space) ``` @@ -239,7 +261,7 @@ The only difference from Artistic QR-Code mentioned above is that you should inp ​ -## Dependencies 依赖库 +## Dependencies * [pillow](https://pypi.python.org/pypi/Pillow/3.3.1) * [numpy](https://pypi.python.org/pypi/numpy) @@ -248,13 +270,11 @@ The only difference from Artistic QR-Code mentioned above is that you should inp -*(**TIPS**: Without a installed [**MyQR**](https://pypi.python.org/pypi/MyQR/1.0.0), you should use `pip install -r requirements.txt` to ensure you have all dependencies.)* - -*（**提示**：如果没有安装 [**MyQR**](https://pypi.python.org/pypi/MyQR/1.0.0) ，使用命令`pip install -r requirements.txt` 来安装所有依赖的库。）* +*(**TIPS**: Without a installed [**MyQR**](https://pypi.python.org/pypi/MyQR), you should use `pip install -r requirements.txt` to ensure you have all dependencies.)* -## Environment 运行环境 +## Environment * Linux, Python 3 * Windows, Python 3 @@ -264,6 +284,6 @@ The only difference from Artistic QR-Code mentioned above is that you should inp ​ -## License 协议 +## License * GPLv3 \ No newline at end of file