Skip to content

Commit 1d9b976

Browse files
ExcaliburZeroExcaliburZero
committed
Add program documentation
Add documentation on how to use the program.
1 parent 43596e6 commit 1d9b976

File tree

8 files changed

+300
-11
lines changed

8 files changed

+300
-11
lines changed

‎README.md‎

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,44 @@
1-
# Blendplot [![Travis CI Status](https://api.travis-ci.org/ExcaliburZero/blender-astro-visualization.svg)](https://travis-ci.org/ExcaliburZero/blender-astro-visualization) [![Coverage Status](https://coveralls.io/repos/github/ExcaliburZero/blender-astro-visualization/badge.svg?branch=master)](https://coveralls.io/github/ExcaliburZero/blender-astro-visualization?branch=master)
1+
# Blendplot [![Travis CI Status](https://api.travis-ci.org/ExcaliburZero/blender-astro-visualization.svg)](https://travis-ci.org/ExcaliburZero/blender-astro-visualization) [![Coverage Status](https://coveralls.io/repos/github/ExcaliburZero/blender-astro-visualization/badge.svg?branch=master)](https://coveralls.io/github/ExcaliburZero/blender-astro-visualization?branch=master) [![Documentation Status](https://readthedocs.org/projects/blendplot/badge/?version=latest)](http://blendplot.readthedocs.io/en/latest/?badge=latest)
22
Blendplot is a command line application for generating 3D data plots for use in Blender.
33

44
```
5-
$ python3 blendplot abc.csv abc.obj period amplitude_Iband magnitude_Iband -c category
5+
$ blendplot abc.csv abc.obj period amplitude_Iband magnitude_Iband -c category
66
Wrote plot file to abc.obj
77
Plotted 37099 points in 1.531214 seconds
88
```
99

1010
![An example of a model generated with Blendplot using data from the OGLE IV lmc survey](img/render_01.png)
1111

12+
## Installation
13+
To install Blendplot from source you can run the following commands.
14+
15+
```
16+
git clone https://github.com/ExcaliburZero/blender-astro-visualization.git
17+
cd blender-astro-visualization
18+
pip install ./
19+
```
20+
1221
## Usage
1322
Blendplot allows you to generate a 3D data plot model by specifying a dataset file, the output model file (`.obj`), and the names of the three (x,y,z) columns you want to plot. Currently it only supports `.csv` input data files. The commad structure to run blendplot is as follows.
1423

1524
```
16-
python3 blendplot INPUT_FILE OUTPUT_FILE X Y Z
25+
blendplot INPUT_FILE OUTPUT_FILE X Y Z
1726
```
1827

1928
For example, to create a model from a data file `data.csv` using the columns `height`, `weight`, and `cost` and output to a file `model.obj` you would run the following command.
2029

2130
```
22-
python3 blendplot data.csv model.obj height weight cost
31+
blendplot data.csv model.obj height weight cost
2332
```
2433

2534
Once you have used the script to generate the model file, you can then import it into Blender by going to `File > Import > Wavefront (.obj)` and selecting the model file.
2635

2736
![Importing the model file into Blender](img/blender_obj_import.png)
2837

29-
### Categories
30-
To plot data that is grouped into categories, you can use the `-c` flag and specify the name of the column to group the data points by. Each different category will be its own object in the resulting model. This will allow you to easily style the groups with different materials.
31-
32-
```
33-
python3 blendplot data.csv model.obj height weight cost -c category
34-
```
38+
## Documentation
39+
For futher in-depth information on how to use Blendplot, see the documentation at the link below.
3540

36-
![The objects created from a plot with categories](img/category_objects.png)
41+
* [Blendplot - Read The Docs](https://blendplot.readthedocs.io)
3742

3843
## Licensing
3944
The source code for Blendplot is available under the [MIT License](https://opensource.org/licenses/MIT), see `LICENSE` for more information.

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SPHINXPROJ = Blendplot
8+
SOURCEDIR = .
9+
BUILDDIR = _build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/conf.py‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Blendplot documentation build configuration file, created by
4+
# sphinx-quickstart on Tue May 23 22:44:55 2017.
5+
#
6+
# This file is execfile()d with the current directory set to its
7+
# containing dir.
8+
#
9+
# Note that not all possible configuration values are present in this
10+
# autogenerated file.
11+
#
12+
# All configuration values have a default; values that are commented out
13+
# serve to show the default.
14+
15+
# If extensions (or modules to document with autodoc) are in another directory,
16+
# add these directories to sys.path here. If the directory is relative to the
17+
# documentation root, use os.path.abspath to make it absolute, like shown here.
18+
#
19+
# import os
20+
# import sys
21+
# sys.path.insert(0, os.path.abspath('.'))
22+
23+
24+
# -- General configuration ------------------------------------------------
25+
26+
# If your documentation needs a minimal Sphinx version, state it here.
27+
#
28+
# needs_sphinx = '1.0'
29+
30+
# Add any Sphinx extension module names here, as strings. They can be
31+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
32+
# ones.
33+
extensions = ['sphinx.ext.autodoc',
34+
'sphinx.ext.viewcode']
35+
36+
# Add any paths that contain templates here, relative to this directory.
37+
templates_path = ['_templates']
38+
39+
# The suffix(es) of source filenames.
40+
# You can specify multiple suffix as a list of string:
41+
#
42+
# source_suffix = ['.rst', '.md']
43+
source_suffix = '.rst'
44+
45+
# The master toctree document.
46+
master_doc = 'index'
47+
48+
# General information about the project.
49+
project = u'Blendplot'
50+
copyright = u'2017, Christopher Wells'
51+
author = u'Christopher Wells'
52+
53+
# The version info for the project you're documenting, acts as replacement for
54+
# |version| and |release|, also used in various other places throughout the
55+
# built documents.
56+
#
57+
# The short X.Y version.
58+
version = u''
59+
# The full version, including alpha/beta/rc tags.
60+
release = u''
61+
62+
# The language for content autogenerated by Sphinx. Refer to documentation
63+
# for a list of supported languages.
64+
#
65+
# This is also used if you do content translation via gettext catalogs.
66+
# Usually you set "language" from the command line for these cases.
67+
language = None
68+
69+
# List of patterns, relative to source directory, that match files and
70+
# directories to ignore when looking for source files.
71+
# This patterns also effect to html_static_path and html_extra_path
72+
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
73+
74+
# The name of the Pygments (syntax highlighting) style to use.
75+
pygments_style = 'sphinx'
76+
77+
# If true, `todo` and `todoList` produce output, else they produce nothing.
78+
todo_include_todos = False
79+
80+
81+
# -- Options for HTML output ----------------------------------------------
82+
83+
# The theme to use for HTML and HTML Help pages. See the documentation for
84+
# a list of builtin themes.
85+
#
86+
#html_theme = 'alabaster'
87+
import sphinx_rtd_theme
88+
89+
html_theme = "sphinx_rtd_theme"
90+
91+
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
92+
93+
# Theme options are theme-specific and customize the look and feel of a theme
94+
# further. For a list of options available for each theme, see the
95+
# documentation.
96+
#
97+
# html_theme_options = {}
98+
99+
# Add any paths that contain custom static files (such as style sheets) here,
100+
# relative to this directory. They are copied after the builtin static files,
101+
# so a file named "default.css" will overwrite the builtin "default.css".
102+
html_static_path = ['_static']
103+
104+
105+
# -- Options for HTMLHelp output ------------------------------------------
106+
107+
# Output file base name for HTML help builder.
108+
htmlhelp_basename = 'Blendplotdoc'
109+
110+
111+
# -- Options for LaTeX output ---------------------------------------------
112+
113+
latex_elements = {
114+
# The paper size ('letterpaper' or 'a4paper').
115+
#
116+
# 'papersize': 'letterpaper',
117+
118+
# The font size ('10pt', '11pt' or '12pt').
119+
#
120+
# 'pointsize': '10pt',
121+
122+
# Additional stuff for the LaTeX preamble.
123+
#
124+
# 'preamble': '',
125+
126+
# Latex figure (float) alignment
127+
#
128+
# 'figure_align': 'htbp',
129+
}
130+
131+
# Grouping the document tree into LaTeX files. List of tuples
132+
# (source start file, target name, title,
133+
# author, documentclass [howto, manual, or own class]).
134+
latex_documents = [
135+
(master_doc, 'Blendplot.tex', u'Blendplot Documentation',
136+
u'Christopher Wells', 'manual'),
137+
]
138+
139+
140+
# -- Options for manual page output ---------------------------------------
141+
142+
# One entry per manual page. List of tuples
143+
# (source start file, name, description, authors, manual section).
144+
man_pages = [
145+
(master_doc, 'blendplot', u'Blendplot Documentation',
146+
[author], 1)
147+
]
148+
149+
150+
# -- Options for Texinfo output -------------------------------------------
151+
152+
# Grouping the document tree into Texinfo files. List of tuples
153+
# (source start file, target name, title, author,
154+
# dir menu entry, description, category)
155+
texinfo_documents = [
156+
(master_doc, 'Blendplot', u'Blendplot Documentation',
157+
author, 'Blendplot', 'One line description of project.',
158+
'Miscellaneous'),
159+
]
160+
161+
162+

‎docs/getting_started.rst‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
.. _getting_started:
2+
3+
Getting Started
4+
===============
5+
6+
To introduce you to Blendplot, we will show how to take a simple dataset, plot it using Blendplot, and then load the created model into Blender. The dataset we will be using is a dummy dataset for products sold in a supermarket.
7+
8+
Getting the data
9+
----------------
10+
11+
This dataset contains information on items and includes their product name, cost, weight, height, quantity, and type. The dataset is defined below.
12+
13+
::
14+
15+
"product","cost","weight","height","quantity","type"
16+
"milk",8.99,10.0,2.0,25,"food"
17+
"chocolate",5.99,15.2,0.5,10,"food"
18+
"bannana",2.99,2.0,0.5,20,"food"
19+
"television",199.99,100.0,10.2,3,"electronic"
20+
"laptop"149.99,5.0,1.0,5,"electronic"
21+
22+
Copy the above data and save it into a file named ``items.csv``.
23+
24+
Creating the model
25+
------------------
26+
27+
Now that you have the data file, you can begin plotting it. First go to the directory where you saved the ``items.csv`` file in the command line.
28+
29+
To begin, we will just plot the cost, weight, and height of the items. You can create the model for this plot in a file ``plot.obj`` by running the following command.
30+
31+
::
32+
33+
$ blendplot items.csv plot.obj cost weight height
34+
Wrote plot file to plot.obj
35+
Plotted 5 points in 0.017454 seconds
36+
37+
Loading the model into Blender
38+
------------------------------
39+
40+
Now that you have created the model file ``plot.obj`` you can now import it into Blender.
41+
42+
When you start up Blender, first delete the starting cube. Then go to ``File > Import > Wavefront (.obj)`` and select the ``plot.obj`` file that you created.
43+
44+
.. image:: ../img/blender_obj_import.png
45+
:height: 600px
46+
:width: 500px
47+
:scale: 100 %
48+
:align: center
49+
50+
Once you have imported the model file, you should now have an object consisting of the plotted data points.
51+
52+
.. image:: ../img/items_blender.png
53+
:height: 336px
54+
:width: 383px
55+
:scale: 100 %
56+
:align: center
57+
58+
Now that you have the plot object you can make any changes you want to the object materials and scene and create rendered images or animations using the data.
59+
60+
.. image:: ../img/items_render.png
61+
:height: 450px
62+
:width: 800px
63+
:scale: 100 %
64+
:align: center
65+
66+
This dataset was a bit small, but Blendplot supports very large datasets as well. Feel free to try it with your own datasets and see how they look.

‎docs/index.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Blendplot
2+
=========
3+
4+
Blendplot is a Python application for generating 3D model scatter plots of data to use in the 3D modeling software Blender. It can take ``.csv`` data files with labeled columns and create ``.obj`` models of scatter plots using the specified columns.
5+
6+
.. image:: ../img/render_01.png
7+
:height: 600px
8+
:width: 500px
9+
:scale: 100 %
10+
:align: center
11+
12+
.. toctree::
13+
:maxdepth: 2
14+
:caption: User Documentation
15+
16+
getting_started
17+
more_features

‎docs/more_features.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
.. _more_features:
2+
3+
More Features
4+
=============
5+
6+
Plotting Categories
7+
-------------------
8+
9+
To plot data that is grouped into categories, you can use the -c flag and specify the name of the column to group the data points by. Each different category will be its own object in the resulting model. This will allow you to easily style the groups with different materials.
10+
11+
::
12+
13+
blendplot data.csv model.obj height weight cost -c category
14+
15+
.. image:: ../img/category_objects.png
16+
:height: 321px
17+
:width: 280px
18+
:scale: 100 %
19+
:align: center

‎img/items_blender.png‎

4.59 KB
Loading

‎img/items_render.png‎

2.94 KB
Loading

0 commit comments

Comments
 (0)