Week 01 - Getting started

Goals

Set up this website
Think about a final project
Formalise these first ideas

Project Management

Setting up the version control, the web development environment and creating the website

Overview

Version control and Gitlab forge

Versioning allows you to keep track of your work's evolution from the start, including adding new files and how they are modified. Moreover, multiple versions of the same file can be edited at the same time by different users, using branches of a history tree. Whenever a user is ready to submit their improvements, the version control system offers to merge both version in an easy and customizable way. Finally, using a version control software allows you to reach and revert to any previous state of the project.

Git is the standard version control software. Apache subversion (svn) or mercurial are similar alternatives. The principle of version control can also be integrated in other softwares that are not dedicated to versioning. For example, Google Docs, or CAD softwares such as Fusion 360 gives the possibility to track the modifications of several members of a team.

Versioning is particularly suitable for text files, as it evaluates and displays the differences between two states of a file.

During the Fabacademy, repositories are created and hosted on the Fabacademy forge for each student. A repository is a project under version control that can be shared with other people. A forge (such as Github or Gitlab) is a website where repositories are hosted, either publically or in private mode. Compared to the simple use of git, forges provide additionnal collaboration tools to discuss and eventually integrate improvements through merge / pull requests.

The Fabacademy's forge offers a simple way to write and publish the students documentation website, while offering all the features that come with versioning and the use of a common forge, gitlab.fabcloud.org. First of all it keeps all the documentation website sources in the same place. Also, the Fabacademy forge allows students to run CI jobs whenever they push changes to their repository, which comes handy for publishing their static webpage documentation easily (thanks to the file gitlab-ci.yml). Finally, it's convenient to keep track of modifications either in the documentation's content itself or other source files (Kicad projects, arduino files, etc.).

Building the documentation website

We have some things to set up in order to start documenting.

As said previously, a git repository has been created for each student on the Fabacademy's forge. An HTML/CSS template has been provided for us to start.

I learned and taught some HTML/CSS/Javascript in previous experiences, but obviously this will not be the fastest way to keep the documentation updated all along the Fabacademy. At least that's what my instructor told me and he's been through the Fabacademy too, so I'll follow his advice and go for Markdown editing. Markdown is a lightweight markup language, very efficient to write structured documents using simple syntax.

MkDocs is a common solution among Fabacademy students to generate their website by automatically parsing the markdown syntax.

MkDocs is a fast, simple and static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file (mkdocs.yml).

In a nutshell, mkDocs is run everytime I push on main, which generates my documentation website. The html content is transcripted from the .md files in my repository. A simple CSS styling is provided with mkDocs, and I added the theme Material for MkDocs, which offers clean styling and other features to customize a website build thanks to MkDocs.

Moreover, it's always possible to add extra CSS rules, by adding an extra.css file with some styling rules overwriting the Material rules (see more below in the extra css section). I used this extra stylesheet to manage the colors, spacing, fonts, borders, etc.

Finally, the markdown extension md_in_html also allow me to include pure HTML in my pages, for example to embed external content with iframe tags or make a customized homepage.

I use the editor Visual Studio Code to edit locally my website files. I can preview my site with a local server by running the instruction mkdocs build and mkdocs serve in the terminal. I then commit my changes, and push my modifications to the main branch, which runs the CI and build the site. A few seconds later, it's online!

You can find all the detailed steps of the setup below.

git setup

As my computer is brand new I had almost everything to install, so I took all the steps from the start. Here are the major steps :

give full access to the Terminal

As I said my computer is brand new, so I really had to start from scratch. Also it's my employer's computer and could have some specific restrictions, so it took me some minutes to realise that the Terminal hadn't full access to the disk by default. To grant full access, I went in System Preferences then Security and Privacy then added Terminal to 'Full Access'

install homebrew and command lines tools

Not sure the command lines tools were necessary () but I installed them anyway. xcode-select --install

In order to install git I installed homebrew (https://brew.sh/)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)")

install git

cd /Users/clara/Documents/gitfiles/

I created a folder gitfile (where I'll ultimately clone my repository)

git init
git config --global user.name myName and git config --global user.email name@example.com

clone the repository with ssh

I proceeded as explained here : https://docs.gitlab.com/ee/user/ssh.html#generate-an-ssh-key-pair

generate an SSH key pair ssh-keygen -t ed25519 -C "fabacademy"
copy the SSH public key

tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy

add the public key to my GitLab account

I log into my GitLab account in a browser in order to add the public key (more info here : https://docs.gitlab.com/ee/user/ssh.html#add-an-ssh-key-to-your-gitlab-account)

check that I have access to the server

ssh -T git@gitlab.fabcloud.org

That sends me back a Welcome message

git clone with SSH

I opened the repository I wanted to clone, selected "clone" then copied the text in "Clone with SSH", the pasted it in the terminal after this instruction git clone

installing MkDocs

MkDocs is a static site generator that will allow me to write down my documentation in Markdown. I followed this MkDocs guide : https://www.mkdocs.org/user-guide/installation/. As written, I first need to install Python to make it work.

install python

I simply used the installer for macOs.

check the python version

I wanted to check if python was correctly installed by running `python --version. It didn't work and I had to ask some human help to find out I needed to replace pythonby python3. Oops! So here is the correct command line which send me back the version I installed: python3 --version

check if pip is installed

pip --version

in my case: install pip

I read that pip could have been installed at the same time as python, but that was not the case for me. So I installed it by downloading get-pip.py (https://bootstrap.pypa.io/get-pip.py), putting it in the right directory then entering python3 get-pip.py

installing MkDocs

pip install mkdocs Check if everything is ok : mkdocs --version

Create your MkDoc project

create a new project

Go in the correct folder then mkdocs new my-project then mkdocs build

test on a local server

In the right folder, type mkdocs serve. Then open your browser and go to http://127.0.0.1:8000/. You should now see the default home page being displayed.

open it in Visual Studio Code

I downloaded Visual Studio Code (you can use any editor you like), then opened the cloned directory, reorganised my files (I deleted the template's public folder and replaced it by the mkdocs folder's content).

commit and push in Gitlab

You should now see all your local files synchronizing in GitLab.

edit the gitlab-ci.yml file

Edit the file .gitlab-ci.yml by replacing its content with the following :

image: python:latest
pages:
  stage: deploy
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

edit the mkdocs.yml file

Edit the mkdocs.yml file by adding at least these information:

site_name: Fabacademy 2023 - Your Name
site_url: https://fabacademy.org/2023/labs/sorbonne/students/your-name

Now we're ready to go with Mkdocs! In my case in wanted to add a Mkdocs theme to improve the design. I am using Material.

Using a theme and customising it

pip install mkdocs-material

edit the mkdocs.yml file

Add the following to the mkdocs.yml

theme:
    name: material

add a custom stylesheet

Create a "stylesheets" folder if it doesn't exist yes, and add a file extra.css inside this folder.

link the stylesheet

Link the stylesheet extra.css by adding the following lines to the mkdocs.yml :

extra_css:
  - stylesheets/extra.css

edit the CSS rules in extra.css

Edit the styles you want to customize, such as colors and fonts.

Some of my customizations

Colors

I may change my color chart, but for now I am using these variables (defined in the template and used in various elements):

:root {
    --md-default-fg-color: #220905;
    --md-primary-fg-color: #34110A;
    --md-accent-fg-color:  #491A0B ;
    --md-primary-fg-color-light: #59200D;
    --md-secondary-fg-color: #5141ff;
    --md-secondary-fg-color-light: #aba6de;
    --md-secondary-bg-color: #ccd7c5;
    --md-default-bg-color: #ece5dc;
    --md-primary-bg-color: #fdf4e9;
    --md-accent-bg-color: #f7c9f5 ;
    --md-accent-bg-color-dark: #f290ff;
  }

In Visual Studio Code I have a small visualization of the color.

At this moment my website color chart is the following:

link to edit the palette in coolors

I am using two sidebars, one giving the general architecture (you have to create folders containing your .md files if you want subsections), and one for the table of contents.

I added this line in mkdocs.ymlto integrate them :

    features:
      - navigation.sections

At first I had a problem with my table of contents because I used several h1. Using h2's instead of h1's allowed me to have a relevant hierarchy. Also, I found that the level of depth was too big, so I reduced the depth by adding these instructions in the mkdocs.yml:

markdown_extensions:
  - toc:
      toc_depth: 3

Icon

To change the default icon of the theme in the header, you can rely on one of the numerous icons provided by materials. For this coffe maker icon :coffee-maker: I would need to add the following in my mkdocs.yml :

theme:
    icon:
      logo: material/coffee-maker

Finally my mkdocs.yml file content is currently:

site_name: Fabacademy 2023 - Clara Devanz
site_url: https://fabacademy.org/2023/labs/sorbonne/students/clara-devanz

theme:
    name: material
    features:
      - navigation.sections
    icon:
      logo: material/coffee-maker

extra_css:
  - stylesheets/extra.css

markdown_extensions:
  - toc:
      toc_depth: 3

Font

I changed some headlines fonts for the font Roboto Slab.

  .md-typeset h2 {
    color : var(--md-default-fg-color);
    font-family: 'Roboto Slab', serif;
    font-weight: 400;
    }

Outline borders and rounded corners

I also added some outlines and rounded corners to some elements, such as h2 and h3, but also md-content. Here is how I completed my rules for h2

  .md-typeset h2 {
    background-color: var(--md-accent-bg-color);
    color : var(--md-default-fg-color);
    font-family: 'Roboto Slab', serif;
    font-weight: 400;
    border-radius: 0.3rem;
    padding: 0.2em 0.4em;
    outline : solid;
    font-size: 1.2rem;
    }

Principles and Practices

Putting down the first ideas for the final project

Previous experiences

In a previous learning experience, I worked on a quite theoretical individual final project. At that moment I wanted to make a project that had a purpose. In my case I wanted to create a pedagogical device that would allow people to manipulate some not-so-intuitive concepts. At that moment I was quite into critical thinking, and there's a formula you meet quite often, which looks quite simple but is hard to feel intituively if you're not used to it. If you're familiar with logic and maths applied to critical thinking, you probably met this formula, it's known as the Bayes' formula. It was very exciting to invent how to manipulate these probability concepts. Here is the object it led to, in French la machine de vraisemblance that you could translate as the plausability machine

Bayes' formula : 
P(H/0)=P(H)*P(O/H)/P(O)

Where:
H is the hypothesis
O is an observation
P(H/O) is H's plausibility a posteriori after O has been observed
P(O/H) is the probability to observe O when H is true
P(O) is the probability to observe O
P(H) is the plausibility a priori of the hypothesis H

Basically the idea was to set the prior plausibility with a rotary encoder (the value was visualized by the upper led strip), then to add an obervation probability value with a "lens" (acrylic disk with NFC tag) and then to calculate the probability P(H/O) that interests us (visualized by the bottom led strip).

Here is the not-fully fonctional prototype:

Well the packaging was atrocious (cables everywhere, we had very little time and not so much tools for electronics) and it didn't fully worked. It sadly ended on a shelf waiting for the day I'll be interested again by that object.

Initial thoughts for my Fabacademy final project

This time, I want to work on a very different proposition. I want to give space to more experiments, to create a much more modular device. I wish to work on something reconfigurable, not a static object that will have only one place in my life. And maybe which could find a place in the life of some other people. Also, I'm not sure I want to work on something so function-oriented as my Bayesian machine. I am close to say that I want to work on something useless.

So, with this experience and my new approach in mind, I started writing down some very general ideas that would interest me to work on. Here are some of them that actually led me to my first idea.

textures, materials
light, light filters and diffusion
hide the technology
create a tool

After some brain processing here is the idea that emerged:

A tool to experiment light art

You might be used to practicing art through a variety of media, thanks to some tools or instruments. Maybe you have experience performing graphic arts such as painting with watercolor, or drawing with pens. You might also have skills producing and arranging sounds with the help of a musical instrument or a computer. My intention with this project is to provide a small set of tools to explore light in an esthetic way.

Light interests me as a medium because most people - including me - don't have so much representations about light art. One will have less stereotypes about what a light creation would look like than about a renaissance piece or a techno track. All the representations, all the codes of light aesthetic are still a bit vague in our minds, which could let us explore quite freely that discipline. I also believe one can have an immediate and intuitive sense of light aesthetic, because it is such a natural feeling that we experience all the time. Most of the time, we don't act consciously on light, we are not even paying so much attention to how it interacts with our world, how it gives us the sense of color, depth, texture. So I am very curious about creating such an environment for people to discover how does it feel to manipulate light and to create their piece of light!

Prior knowledge and inspirations

Creating a set of tools before the practice being very formalised can be confusing, because I also have ton invent the rules, and I have no prior knowledge in light art. I have even no prior knowledge in color and light in visual arts such as cinema, painting... I can imagine there are a lot of keys to understand light, for example how the shadow is colored compared to the light, and some rules or tips in the use of light, for example in movies. On another angle, I studied basic optic science during some physics lesson in my scholarity, but that felt more like scratching the surface of a much more complex discipline. So, I believe I'll get more familiar with light while making and playing with my device!

I am also conscious that a lot has already been explored in light art, that there are some famous artists, amazing pieces, and I believe that there is a lot of research and innovation in particular in digital arts. For now I'm really not putting myself in an artistic position neither academic, more like a tool-crafter learning by doing and playing.

About the inspiration, I can remember visiting an exhibition of Dan Flavin's art in Paris when I was not yet an adult, probably at the Musée d'Art Moderne in 2006. I think my feelings about this exhibition were both upset, as you can be when you see a so simple setup being under the spotlight of major art show-business, and enchanted. It is described as minimalistic art - and you can see why on this picture - but yet I was very impressed by the beauty and strangeness of this experience.

Later, I got really interested in digital art in general, and followed an interdisciplinary master called Art Science Technology in Grenoble, France. I regularly visited digital art exhibitions, and light installations were quite common in such places. But I cannot recall any piece of art I saw that focused only on light, I must have forgot these. During these years, the Fête des Lumières in Lyon was also driving more and more attention and I attended several editions. Nevertheless it was at that time mainly focused on light projections and music-and-light shows.

In my personnal projects I also have a tendency to put led strips everywhere, starting with my clothes!

Feeding my interest in light I can also mention:

a discussion with a friend about the color of the shadow in painting
science videos about light principles and more generally wave physics
playfullness and pleasure I get from arranging colors
a piece of furniture and a piece of art seen at the exhibition Colors, etc. at the Tri postal, Lille, based on dichroïc properties
a collaborative project I contributed to with the Fablab Carrefour Numérique, resulting in a diorama concept
an exhibition I visited with a flashlight in Grenoble allowing us to appreciate all the texture of some historical stones (the context is very vague in my mind but I kept this observation about texture with me)
how I experience light in my everyday life

Defining the device

Honestly it's way too fresh in my head to have an idea of the designs, even the list of elements I want to create are not clear at all in my mind. I am quite convinced I'll discover new directions while going further and experimenting the first bricks of my project. But here are the first thoughts anyway.

Guidelines

I have in my mind the following expectations about my project:

Modular - It is a set of tools that you wouldn't use all at the same time, depending on what you want to create or explore. Thus you could have several types of texture pannels, a choice of windows to frame the light, various filters to place in front of the light source, etc.
Playable - I would like to give access to the large possibilities offered by programmable LEDs, but without modifying the code manually each time, nor using a web interface or something similar. I want to explore the gesture a person would use to play with the device, and define controls according to what may feel more natural, logical and fun.
Unpredictable - This project is about exploring a medium, so of course it will be quite unpredictable in a certain extense, because one wouldn't know precisely the result of their action before doing them. But also I want to erase the sense of the code and numbers that underlies the device, in particular regarding the color coding. So I am not aiming at total unpredictability, more at a way to prevent the total-control thing.

Also, it is important to mention that at that stage of my project, I mostly want to observe the light diffusion in space, and not the direct emission of LEDs nor something like a screen.

Elements of the set of tools

Elements that could be provided

Here are the roles I am hiring:

The first roles:

light sources

I could use any kind of light source, but it would be a shame not to rely on programmable LEDs. As I said I see them at first as sources of light, but if they're good looking and can also play an aesthetic role for themselves, that's even better.

screens

I need at least one screen to observe light and shadows. That could be a simple piece of paper. I prefer having several screens to take advantage of the 3D property of that medium. It could be some kind of folding paper screen

obstacles

Technically obstacles are also some kind of screens because they'll interrupt light on a surface. Obstacles are placed before the screen so you can also observe how lights create the volumic sensation, how the different surfaces are lit. Moreover, they cast shadows on the screen, that you also want to observe. I imagine them totally white, they could be some paper foldings and/or wood simple shapes.

The secondary roles

In addition to these first roles, I could also provide:

textures

Monochrome "2D" textures, such as textile, corrugated cardboard, heavily textured paper, or reflecting surfaces. They could act as a mix between screens and obstacles, and be placed either on a screen, or in the middle of the scene.

filters

Placed on the way of a light source, they could change their property (like a dichroïc polarizer) or their diffusion

windows

Some sort of negative screens: they block the light except in a window cut into a pannel. They allow to structure light effects visually.

lenses

I am not looking into a scientific light experiment approach, but it may be useful to use some lenses to focus the light.

The led controls

primary color dispensers

I would like to give the possibility to mix the primary colors (of light, which are red green and blue) as one would mix gouache painting colors. I'll have five color dispensers:

Red
Green
Blue
White (if I use RGBW leds)
Black - to set the brightness

color palette

This is where you would mix your primary colors. Then you could "fill" your light sources with the color in the color palette to change them. If the light element contains several neopixels, they could be lit progressively if you keep this element in contact with the color palette.

mixing colors

If I use led strips, it would be interesting to be able to "fill" with a color either one tip or another, thus allowing to fill both tips with different colors. It would be quite fun to give the possibility to "mix" these colors with a gesture like shaking - for example to create a color gradient.

The environment

space structure

I don't know yet how to solve this question. I believe it's important to have a kind of definition of the space you're working in. For example in painting your space is your canvas. In music it would probably be time, and in theater both a scene and a duration. I thus would like to define a 3D space, maybe with pannels. These pannels could be the same as the screens, but not necessarily. Also, this structure could allow us to hang the lights (either mechanically with hooks or similar, or with magnets).

dark room

I'll probably have to work in a dark environment to fully appreciate the effect of light. So I'll need a small dark room or dark working place. Needless to say that this environment constraint will certainly affect all my elements design, as they need to be manipulated in low lighting conditions.

Development

If I stick with the project as described above, the minimum viable product would be the light sources and the color palette system. I will thus probably focus on these elements before creating a whole toolkit. Nevertheless I probably shouldn't wait until these minimal elements are fully functionnal to test if my general concept is relevant. Here's how I could organise the first development steps

assemble a basic led strip circuit
test what I can expect from the light diffusion
test the interaction of the light emitted with paper pannels, obstacles, textures...
evaluate the positions I would like to give to the light sources
and how the space should be structured
create a minimal color palette circuit
add communication components and code to the light source circuit
test the communication between the light source and the color palette
evaluate the gesture
integrate all of the above in the light source design

Then I can move forward to the next steps:

creating the color dispensers
test the interaction between the color dispensers and the color palette
take in account the light source design to design the color palette
explore the gesture
explore the sense of space and interaction with obstacles, screens, textures...
build some test elements (screens, textures, obstacles)
conceptualise the space structure
build it
test!
establish some coherent design rules to apply to all elements of the kits (if possible)
design and develop more elements of the kit (starting with the more importants, such as the screens and some obstacles)

Week 01 - Getting started

Project Management

Overview

Version control and Gitlab forge

Building the documentation website

git setup

give full access to the Terminal

install homebrew and command lines tools

install git

clone the repository with ssh

installing MkDocs

install python

check the python version

check if pip is installed

in my case: install pip

installing MkDocs

Create your MkDoc project

create a new project

test on a local server

open it in Visual Studio Code

commit and push in Gitlab

edit the gitlab-ci.yml file

edit the mkdocs.yml file

Using a theme and customising it

edit the mkdocs.yml file

add a custom stylesheet

link the stylesheet

edit the CSS rules in extra.css

Some of my customizations

Colors

Navigation

Icon

Font

Outline borders and rounded corners

Principles and Practices

Previous experiences

Initial thoughts for my Fabacademy final project

A tool to experiment light art

Prior knowledge and inspirations

Defining the device

Guidelines

Elements of the set of tools

Development