Skip to content

Commit 306f075

Browse files
ponchioponchio
committed
working on documentation
1 parent 144cc86 commit 306f075

33 files changed

+368
-114
lines changed

‎relightlab/docs/formats/config.md

+11-8
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,22 @@
1-
## Configuration
1+
## Relightlab Configuration
2+
3+
<!-- The user configuration is stored locally and deals with a few preferences
4+
that the user might want to preserve from one job to the next -->
25

36
# Appearance
7+
<!-- dark theme vs light theme -->
48

59
# Casting
10+
<!-- which port will be used for local casting -->
611

712
# Performances
13+
<!-- basically set the amount of RAM and number of threads (%CPU, roughly) -->
814

915
# Cache
16+
<!-- folder for cached processing files (not used at the moment, but could be
17+
thumbnails, results of align processing etc) -->
1018

19+
# Metadata
1120

12-
# Defaults
13-
14-
Defaults will be usually overwritten when value is changed in a dialog.
15-
16-
Jpeg Quality (95).
17-
18-
Web format (deep zoom)
21+
<!-- author, organization, if we are going to save it or not etc. -->
1922

‎relightlab/docs/formats/dome.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Dome configuration file format
22

33
Dome configuration is saved in a JSON file (.dome extension) and contains all the informations
4-
related to geometry and calibration of the lights, dimensions, offsets etc.
4+
related to geometry and calibration of the lights.
55

66
| key | value |
77
| --- | --- |

‎relightlab/docs/formats/general.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#Formats
2+
3+
<!-- index of the various formats used -->

‎relightlab/docs/formats/iiif.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#IIIF
2+
3+
<!-- IIP developers gently provided a multiplane tiled tiff export for RTIs, this can
4+
be used by IIP (and other image servers) to serve images following the IIIF protocol -->

‎relightlab/docs/formats/legacy.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#Legacy .ptm .rti formats
2+
3+
<!-- used for visualization and analysis local tools, not suitable for web visualization,
4+
link to RTIViewer -->

‎relightlab/docs/formats/lp.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#LP Ligh directions
2+
3+
<!-- simple text format to represent light directions (xyz)
4+
5+
Number of lines
6+
filename_1 x y z
7+
filename_2 x y z
8+
filename_n x y z
9+
10+
This takes into account only the direction, (relative to the center of the image),
11+
not the 3D position. Can be save and reused, since we usually sort images by name (cameras
12+
use progressive numbers) to associate a light direction to the correct light. -->

‎relightlab/docs/formats/relight.md ‎relightlab/docs/formats/project.md

File renamed without changes.

‎relightlab/docs/formats/web.nd

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
#Web frienly RTI format
2+
3+
<!-- binary files are opaque to the users, harder to parse, and in generally not suited
4+
for the web, where bandwith and latency limits performances. The legacy files were not designed
5+
taking into account web constraint -->
6+
7+
<!-- RTI coefficients are efficiently compressed using images, usually jpg -->
8+
9+
<!-- relight uses a simple structure composed of a json and a few images, this fine if
10+
the images are small for large images, using pyramidal approaches (deepzoom for example)
11+
is advised. -->
12+
13+
<!-- pyramidal image management generate a large number of files, this can create problem managing
14+
and transfering the files, a workaround is tarzoom which concatenate all the images in a single file,
15+
and takes advantage of the 206 range request ability of http protocol to request a segment of a file,
16+
take into account that some http server do not support 206 protocol -->
17+
18+
<!-- another problem is related to the number of http requests (one per image, up to 9 per tile),
19+
some hosting have anti denial of service and limit the number of requests per second, and
20+
fast connections can trigger the limit. Itarzoom compact all the images for the same tile in a single request -->

‎relightlab/docs/gettingstarted.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#Getting started
2+
3+
<!-- Here we guide the user through the steps to create an RTI,
4+
we do not need to cover every detail. -->
5+
6+
1. <a href="#newproject"> Prerequisites </a>
7+
2. <a href="#lights"> Lights </a>
8+
3. <a href="#rti"> Export RTIs </a>
9+
4. <a href="#normals"> Export normals </a>
10+
5. <a href="#view"> View the results </a>
11+
12+
13+
##New project
14+
15+
<!-- relight save the configuration in a .relight project. To creata a project select a folder where the all the images
16+
are (in .jpg format) -->
17+
18+
19+
##Light configuration
20+
21+
<!-- relight needs to know the position/direction of the lights, here we proporse to use an .lp if
22+
present or to use a reflective sphere -->
23+
24+
##Export RTI
25+
26+
<!-- we instruct the user to crop the region of interest, than to select a simple ptm (link to rti/basis.md),
27+
save in web image format, -->
28+
29+
30+
#Working with normals
31+
32+
<!-- we can exporta a normalmap, ensure that the normal is flat (see interface/geometry.md),
33+
and export also a mesh (.ply) or a depthmap -->
34+
35+
#Explore the results
36+
37+
<!-- in the queue tab open the folder to see the images, cast to see the openlime viewer -->

‎relightlab/docs/home.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
1-
### RelightLab
1+
# Documentation
22

33
A selection of topics, links to to tutorials, etc.
44

55
RTI introduction.
66

77
Publishing on the web.
88

9+
## <a href="index.md"> Index </a>
10+
911

1012

1113

‎relightlab/docs/index.md

+9-9
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
### RelightLab
1+
# Index
22

3-
## Index
3+
0. <a href="start/gettingstarted.md"> Getting started </a>
44

5-
# <a href="interface/index.md"> Interface </a>
5+
1. <a href="interface/index.md"> Interface </a>
66

7-
<a href="interface/new_project.md"> New project</a>
8-
<a href="interface/open_project.md"> Open project</a>
7+
1. <a href="interface/new_project.md"> New project</a>
8+
2. <a href="interface/open_project.md"> Open project</a>
99

10-
# <a href="formats/index.md"> File formats </a>
10+
2. <a href="formats/index.md"> File formats </a>
1111

12-
<a href="formats/relight.md"> Relight file format </a>
13-
<a href="formats/config.md"> Relight config file </a>
14-
<a href="formats/dome.md"> Dome file format </a>
12+
1. <a href="formats/relight.md"> Relight file format </a>
13+
2. <a href="formats/config.md"> Relight config file </a>
14+
3. <a href="formats/dome.md"> Dome file format </a>
1515

‎relightlab/docs/interface/domes.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#Dome
2+
3+
<!-- if the images are captured using a dome, you can provide the light directions/positions to relightlab
4+
instead of using reflective spheres.
5+
You can use an .lp (see formats/lp.md)

‎relightlab/docs/interface/general.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#RelightLab inteface
2+
3+
<!-- a little help on the workflow (follow the tabs in order) how crop and light config are remembered and used when exporting,
4+
you can queue the jobs and control them. save as .regligh, etc -->

‎relightlab/docs/interface/geometry.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#Lights geometry
2+
3+
<!-- many RTI software consider the light direction only, as if the lights were infinitely distant,
4+
this approximation is somewhat ok for a visual inspection, but severely distorts the normals.
5+
We can instead take into account for each pixel the real light direction if we can reconstruct
6+
the geometry of the scene: 3d positions of the lights and size of the image -->

‎relightlab/docs/interface/image_list.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
#Image list
2+
3+
<!-- here we can inspect the images (list or thumbnails), rotate the images (in case you forgot to remove the autoorient), and exclude images from rti/normal processing -->

‎relightlab/docs/interface/measurements.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#Measurements
2+
3+
<!-- we can select a segment on the image and assign a length in real life (in mm).
4+
the pixel size and image width an height in real life measures will be computed.
5+
This is need if we want 3d light position processing. see interface/geometry.md -->

‎relightlab/docs/interface/new_project.md

+5-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,11 @@
11
### New Project
22

3+
<!-- this is a test -->
34

4-
A dialog will ask you so select a folder containing the images to be processed.
5+
A dialog will ask you to select a folder containing the images to be processed.
56

6-
All same format (which are supported) and resolution.
7+
All the images needs to be in JPEG format with the same resolution.
8+
9+
Do not crop the images if you plan to use the dome geometry
710

811

‎relightlab/docs/interface/queue.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#Queue
2+
3+
<!-- each processing job (RTI, normals, etc) is performed in background, in this
4+
tab you have a ccess to the list, you can stop, pause and remove jobs -->

‎relightlab/docs/interface/spheres.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#Reflective spheres
2+
3+
<!-- we need you to find the sphere, click on the boundary (minimum is 3), to mark the sphere
4+
points can be removed (select it click delete) or dragged around.
5+
When done the reflections will be automatically computed.
6+
You can re-edit the points later (edit button), verify and eventually manually adjust the
7+
reflections -->

‎relightlab/docs/normals/export.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
##Export
2+
3+
<!-- the normalmap can be saved as a .jpg or a .png, surfaces are saved in .ply .tiff using the same name,
4+
do not save jpg alongside the project images -->

‎relightlab/docs/normals/flattening.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#Flattening normals
2+
3+
<!-- The object might be flat, but the normals are computed using the light direction,
4+
and failing to account for exact light position (or worse just using the direction) and other
5+
phenomena like vignetting, we will get a deformed surface normals -->
6+
7+
##Radial flattening
8+
<!-- we fit a second degree polinomial throuugh the normals assuming the normals will be flat on average,
9+
the resulting normals wont show 'banana' effects -->
10+
11+
##Fourier flattening
12+
<!-- Here we decompoose normal frequencies (like sound) and filter low frequencies (there is a parameter
13+
to tune it, this not only account for the 'banana' problems but also for local deformations (depending on the
14+
parameter value -->

‎relightlab/docs/normals/normalmap.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#Normal maps
2+
3+
<!-- explain what they are, and what they can be used for,
4+
different algorithms exist (we are only using the basic one and hsh at the moment) -->
5+
6+

‎relightlab/docs/normals/surface.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#Generate a 3D surface
2+
3+
<!-- Normal maps can be integrated to create a 3d surface. This process has two main limitations:
4+
one is error accumulation, the other is dealing with discontinuties -->
5+
6+
##Fourier normal integration
7+
8+
<!-- cannot properly deal with discontinuities, it is dense (large meshes, 2 triangles per pixel), and very fast -->
9+
10+
##Bilateral normal integration
11+
12+
<!-- can deal with discontinuties (there is a parameter that basically control the probability
13+
a sudden change in normal is marked as a discontinuity), it is dense, it is very slow -->
14+
15+
#Adaptive surface meshing
16+
<!-- cannot deal with discontinuities but the resulting mesh is reasonably small. Slow.
17+
A parameter controls the precision of the output -->

‎relightlab/docs/readme.md

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
RelightLab documentation.
2+
3+
Reglightlab documentation is organized in a set of .md files.
4+
We have a few, long readable topics (getting started, workflow, etc).
5+
and a set of shorter pages explaining specific topics.
6+
7+
The general file structure as follow, check the files for summary of the content.
8+
9+
General topics:
10+
11+
Getting started /start/gettingstarted.md
12+
New Project
13+
Light directions
14+
Export RTIs
15+
Export normals
16+
View the results
17+
18+
19+
Shorter specific topics:
20+
21+
Interface /interface/general.md
22+
New project /interface/new_project.md
23+
Open project /interface/open_project.md
24+
Image list /interface/image_list.md
25+
Measurements /interface/measurements.md
26+
Spheres /interface/spheres.md
27+
Dome /intercace/domes.md
28+
Geometry /interface/geometry.md
29+
Queue /interface/queue.md
30+
31+
Rti /rti/general.md
32+
Basis /rti/basis.md
33+
Colorspace /rti/colorspace.md
34+
Coefficients /rti/coefficients.md
35+
Format /rti/format.md
36+
Quality /rti/quality.md
37+
Web /rti/web.md
38+
Export /rti/export.md
39+
40+
Normals /normals/normalmap.md
41+
Flattening /normals/flattening.md
42+
3D surface /normals/surface.md
43+
Export /normals/export.md
44+
45+
File formats /formats/general.md
46+
Lp format /formats/lp.md
47+
Dome format /formats/dome.md
48+
Project format /formats/project.md
49+
Web format /formats/web.md
50+
IIIF format /formats/iiif.md
51+
Legacy format /formats/legacy.md

‎relightlab/docs/rti/basis.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#Basis
2+
3+
<!-- difference between PTM, HSH RBF, BLN
4+
5+
which criteria should be used to select one:
6+
7+
sampling: bad sampling -> PTM, HSH
8+
dull materials -> PTM
9+
per pixel light direction -> cannot use RBF
10+
shiny, good sampling -> RBF/BLN
11+
12+
-->

‎relightlab/docs/rti/coefficients.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#Coefficients
2+
3+
<!-- RTI models generate cofficient planes (n float numbers per pixel), this are saved
4+
as images, RGB or other (see colorspace) -->
5+
<!-- PTM and HSH have degrees, but RBF and BLN have a variable number

‎relightlab/docs/rti/colorspace.md

Whitespace-only changes.

‎relightlab/docs/rti/export.md

Whitespace-only changes.

‎relightlab/docs/rti/format.md

Whitespace-only changes.

‎relightlab/docs/rti/general.md

Whitespace-only changes.

‎relightlab/docs/rti/quality.md

Whitespace-only changes.

‎relightlab/docs/rti/web.md

Whitespace-only changes.

0 commit comments

Comments
 (0)