go-image2ascii

README

* go-image2ascii

API service to Convert an Image to ASCII art

There is a command line version of the conversion tool and an http
service built with goswagger.

Built and tested with:
- =go version go1.8.1 linux/amd64=
- =swagger version >=0.9.0=

* Build

** make

Clean up, generate code, test, build, vet, and install http server in a simple way.

** make help

Description of how to use the make cmds.

#+BEGIN_SRC
These 'make' targets are available.

  all                Clean, generate, test, build, vet, install
  clean              Removes all build output
  generate           Generates all code needed
  test               Run the unit tests
  build              Builds the binary
  vet                Runs govendor vet against proejct
  install            Installs the binary to /home/cp16net/gospace/bin
  tools              Installs tools needed to run
  release-base       Builds docker image for release
  build-image        Builds docker image for release
  publish-image      Publish csm docker image to registry
#+END_SRC


* Usage

Once project is installed you can use =${GOBIN}/go-image2ascii= cmd to invoke the CLI.

#+BEGIN_SRC
go-image2ascii converts an image to ascii art.

Usage:
  go-image2ascii [command]

Available Commands:
  convert     Converts an image to acsii art
  help        Help about any command
  http        Run an http server

Flags:
      --config string   config file (default is $HOME/.go-image2ascii.yaml)
  -h, --help            help for go-image2ascii

Use "go-image2ascii [command] --help" for more information about a command.
#+END_SRC

** convert cmd

go-image2ascii convert [-j] <path to file>

#+BEGIN_SRC
Converts an image to acsii art

Usage:
  go-image2ascii convert [full filepath to image] [flags]

Flags:
  -h, --help   help for convert
  -j, --json   output in json format

Global Flags:
      --config string   config file (default is $HOME/.go-image2ascii.yaml)
#+END_SRC

** http cmd

#+BEGIN_SRC
This runs an http web server. (testing this out)

Usage:
  go-image2ascii http [flags]

Flags:
      --bind string   interface to which the server will bind (default "127.0.0.1")
  -h, --help          help for http
  -p, --port int      port on which the server will listen (default 8080)

Global Flags:
      --config string   config file (default is $HOME/.go-image2ascii.yaml)
#+END_SRC

*** example requests

requires curl and jq (optional) installed.

#+BEGIN_SRC
curl -H "Content-Type: multipart/form-data" -X POST --form "uploadfile=@Golang.png" http://127.0.0.1:8080/upload
curl -H "Content-Type: multipart/form-data" -X POST --form "uploadfile=@Golang.png" http://127.0.0.1:8080/upload | jq '.'
curl -H "Content-Type: multipart/form-data" -X POST --form "uploadfile=@Golang.png" http://127.0.0.1:8080/upload | jq -r '.string'
#+END_SRC

* References

** main convert code

- https://gist.github.com/cdiener/10567484
- https://github.com/stdupp/goasciiart
- https://library.launchkit.io/on-the-fly-media-upload-processing-with-go-73995ffe10f3

** gopher images

- Source	http://golang.org/doc/gopher/
- Author	Renee French http://reneefrench.blogspot.com

* Notes

** HTML Output

I expected to serve a simple html form to test via browser from "/"
and "/upload" but this didnt work so well because goswagger doesnt
natively support text/html content type output. I was able to serve it
via test/plain but the mimetype on the response isnt right to show the
html page that is delivered.

This seems like a trivial task but has proven a little more painful
than i'd thought.

Maybe this reference would help.
https://astaxie.gitbooks.io/build-web-application-with-golang/en/04.5.html

** Limits

Limit the size of the uploaded file to 5 mb.

** Validation

Also no initial validation of file types on http headers of the request.

** Image Conversion

Processes the file upload stream directly to the image decoding routine.

The ASCII charactors to represent an image is set to 16
currently. Ideally this could be changed by just using a different
charactor set for the ASCII constant value.

The resizing of the image is done by hard coding the width and using
it to keep the aspect ratio of the image's height the same.

* Dependencies

** govendor

[[https://github.com/kardianos/govendor]]

This seems to be the new way of managing dependencies since i worked
with golang versions 1.4 to 1.6. This tool seems to work pretty well
to update the deps in vendor. Seem many other projects switch to using
this now instead of godeps.

** Cobra and Viper

These two projects have been around a while and widely used in many
projects with golang. There are many contributors and active commits.

[[https://github.com/spf13/cobra][Cobra]] is used as a CLI command generator and makes things very easy to
add new commands or remove commands. Allows for easy generating
documentation of the cmd

[[https://github.com/spf13/viper][Viper]] is used as a configuration manager. It works well with cobra and
handles getting environment variables or command line flag or even
configuration file parameters automatically.

** go-swagger

[[https://github.com/go-swagger/go-swagger]]

I've used swagger in the past and its great for building a REST server
and client model from a single file. The project still looks very
active from pull requests and issues.

I looked at using another framework called iris and decided against it
because there was lots of controversy over how it was maintained. This
libary has claims of being fast and have many features.

One of the drawbacks over what i aimed to deliver was cut short when i
used goswagger because the generated models dont support output of an
html producer. I would liked to have had the html template that i
currently have in the =templates/= folder to be sent on the =/= and
=/upload= paths.

Looks like go-swagger needs more customization to get the text/html
content-type output supported.

** logrus

[[https://github.com/sirupsen/logrus]]

Logrus is a logging library that allows for much more customization of
splitting the logs to multiple outputs and formats. Adding in plugins
can allow transformation of the logs or set output destinations. This
has a way of being configured from a file as well so you dont need to
setup all the logging in the application.

Project seems active with new releases regularly and many contributors.

** testify

[[https://github.com/stretchr/testify]]

Testify is a helper for unit testing and makes things a bit more
straightforward when you are asserting values.

Its been in use for a while but not very active in the last couple
months. I see people begging to get reviews and pull requests merged.

** resize

[[https://github.com/nfnt/resize]]

This was a library that others have used to convert images when i was
looking around. Pretty simple and straighforward libary with some good docs.

The project seems stagnant and not many changes but unless new
features are needed this wouldnt hurt the current use of the libary in
my project.

* Testing

** Unit

Code coverage of critical parts of the application are tested. Left
out any generated code test coverage because this code while core to
the execution and run of the application could change depending on the
version of swagger that you have installed for generation.

** Benchmark

(NONE)

It would be nice to be able to run some simple benchmarking tests to
verify the speed of this routine against another proposed solution in
the future.

** Integration

(NONE)

It would be nice to run this as a separate service and make sure that
the results from end to end are validated with some integration type
tests.

* License

[[LICENSE][Apache License 2.0]]