diff --git a/README.md b/README.md index bffde0751334148e9e498286d01485fa2c6dc03e..0703838e7f34f6024b247a034bead3cd014fd3ff 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,11 @@ This package features a GUI for visualizing behaving larvae and editing discrete behavior tags at each time step. -To run `LarvaTagger.jl`, you will need [`julia>=1.6`](https://julialang.org/downloads/) and some input data file, *e.g.* a `trx.mat` file or a pair of `.spine`/`.outline` files, preferably located in a repository with directory structure: `<screen_name>/<genotype@effector>/<protocol>/<date_time>`. +To natively run `LarvaTagger.jl`, you will need [`julia>=1.6`](https://julialang.org/downloads/) and some input data file, *e.g.* a `trx.mat` file or a pair of `.spine`/`.outline` files, preferably located in a repository with directory structure: `<screen_name>/<genotype@effector>/<protocol>/<date_time>`. -If you are not familiar with Julia, you may appreciate installation helpers such as [JILL.py](https://github.com/johnnychen94/jill.py). -An example install procedure can be found in [`scripts/make_demontrator.sh`](https://gitlab.pasteur.fr/nyx/larvatagger.jl/-/blob/main/scripts/make_demonstrator.sh). +If you are not familiar with installing Julia, you may appreciate installation helpers such as [JILL.py](https://github.com/johnnychen94/jill.py). + +Alternatively, if you have Docker installed, take a look at the [dedicated instructions page](https://gitlab.pasteur.fr/nyx/larvatagger.jl/-/tree/docker/recipes). ## Install @@ -17,6 +18,23 @@ cd LarvaTagger julia --project=. -e 'using Pkg; Pkg.instantiate()' ``` +Calling `instantiate` in a copy of the project is preferred to using `Pkg.add`, +because `LarvaTagger.jl` depends on several unregistered packages. + +Users who would prefer not to clone the repository or implicitly use the shipped `Manifest.toml` file +can follow the following steps instead: + +``` +mkdir LarvaTagger +cd LarvaTagger +julia --project=. -q +julia> +(LarvaTagger) pkg> add https://gitlab.pasteur.fr/nyx/PlanarLarvae.jl +(LarvaTagger) pkg> add https://gitlab.com/dbc-nyx/ObservationPolicies.jl +(LarvaTagger) pkg> add https://gitlab.com/dbc-nyx/TidyObservables.jl +(LarvaTagger) pkg> add https://gitlab.pasteur.fr/nyx/LarvaTagger.jl +``` + ## Run ### Using the Julia interpreter @@ -27,23 +45,23 @@ julia --project=. ``` In the interpreter, to launch the editor, type: ``` -julia> using LarvaTagger; larvaeditor("path/to/data/file") +julia> using LarvaTagger; display(larvaeditor("path/to/data/file")) ``` The first time the editor is loaded, it may take a while for a window in your webbrowser to open, and the data to be plotted. -The Firefox web browser showed better performance than Chrome-like browsers. - To exit the interpreter, type `exit()` or press Ctrl+D. ### Using the `larvatagger.jl` script -The `LarvaTagger/scripts` directory contains a `larvatagger.jl` executable file. -To launch the editor, type: +As an alternative to explicitly launching a Julia interpreter and typing some Julia code, if you cloned the repository, you can run the `larvatagger.jl` script instead: + ``` -scripts/larvatagger.jl open path/to/data/file +scripts/larvatagger.jl open path/to/data/file --browser ``` +The script will also launch a Julia interpreter, and give extra guidance on *e.g.* how to exit the interpreter. + ## Automatic tagging To extend the editor with `MaggotUBA` automatic tagging: @@ -53,16 +71,20 @@ cd MaggotUBA poetry install -vvv cd .. ``` -To let *larvaeditor* know about MaggotUBA, in the Julia interpreter, type: + +If the backend directory is created right in the `LarvaTagger` directory, `LarvaTagger.jl` will automatically find it. + +Otherwise, to let *larvaeditor* know about MaggotUBA or any other backend, in the Julia interpreter, type: ``` -julia> using LarvaTagger; larvaeditor("path/to/data/file"; backend_directory="path/to/MaggotUBA's/parent/directory") +julia> using LarvaTagger; display(larvaeditor("path/to/data/file"; backend_directory="path/to/MaggotUBA's/parent/directory")) ``` + Similarly, to let *larvatagger.jl* know about MaggotUBA: ``` -scripts/larvatagger.jl open "path/to/data/file" --backends="path/to/MaggotUBA's/parent/directory" +scripts/larvatagger.jl open "path/to/data/file" --backends="path/to/MaggotUBA's/parent/directory" --browser ``` -Note however that [`MaggotUBA-adapter`](https://gitlab.pasteur.fr/nyx/MaggotUBA-adapter) requires the actual [`MaggotUBA`](https://gitlab.pasteur.fr/les-larves/structured-temporal-convolution/-/tree/dev-branch) code that is not open access yet. +Note however that [`MaggotUBA-adapter`](https://gitlab.pasteur.fr/nyx/MaggotUBA-adapter) requires the actual [`MaggotUBA`](https://gitlab.pasteur.fr/les-larves/structured-temporal-convolution/-/tree/light-stable-for-tagging) code that is not open access yet. As a consequence, it is likely the installation step fails. The `MaggotUBA` tagging core will be fully released in the near future. diff --git a/recipes/README.md b/recipes/README.md new file mode 100644 index 0000000000000000000000000000000000000000..eab2798d5e99490e51a91ae07aa8bcef696b1d8c --- /dev/null +++ b/recipes/README.md @@ -0,0 +1,55 @@ +# Docker images + +## Getting available images + +Images are published on [Docker Hub](https://hub.docker.com/repository/docker/flaur/larvatagger). + +They ship with `LarvaTagger.jl` and, optionally, with a MaggotUBA-based toy backend for automatic tagging. + +Try: +``` +docker pull flaur/larvatagger:0.5-20220418 +``` + +Beware that images that ship with backends are relatively large files (>6GB). + +## Running an image + +A number of options must be passed to the `docker` command for the container to open a data file: + +``` +docker -iv $(pwd):/data -p 9284:9284 larvatagger open /data/path/to/your/file +``` +with `path/to/your/file` a relative path to your file. + +In the command above, `/data` represents the local directory, made available within the container. +This is required, since no files outside the container can be accessed. + +The port *LarvaTagger.jl* listens to must also be exported with `-p 9284:9284` so that it can be accessed from outside the container. + +Just like the `scripts/larvatagger.jl` script, the docker image admits more commands, including `import`, or options such as `--help`. +For these other commands, neither `-i` nor `-p 9284:9284` are necessary. + +See also standalone script [`scripts/larvatagger.sh`](https://gitlab.pasteur.fr/nyx/larvatagger.jl/-/blob/main/scripts/larvatagger.sh) that wraps `docker` and exposes a simpler interface. For example: + +``` +scripts/larvatagger.sh open path/to/your/file +``` + +## Building an image + +The `scripts/larvatagger.sh` script features a `build` command: + +``` +scripts/larvatagger.sh build +``` + +Optionally, if you have read access to the original MaggotUBA repository, you can fetch include a toy backend with: + +``` +scripts/larvatagger.sh build --get-backend +``` + +In both cases, `larvatagger.sh` will try to run the server and UI using a sample data file expected as file `test/sample_data`. + +Pick a file in the format you expect to most frequently manipulate (either *Choreography* files, FIMTrack v2 csv files, *trx.mat* files as generated by JBM tagging pipeline, etc) and copy it at that location. diff --git a/src/cli.jl b/src/cli.jl index 13b6829914215ee0f0ea48396991e419f365bd0d..288748f3d1f95c0f263026f0144c35d420cb6a28 100644 --- a/src/cli.jl +++ b/src/cli.jl @@ -74,12 +74,11 @@ function main(args=ARGS) server = Server(app, "0.0.0.0", port) if parsed_args["--browser"] JSServe.openurl("http://127.0.0.1:$(port)") - #display(JSServe.BrowserDisplay(), app) elseif verbose @info "The server is listening to http://127.0.0.1:$(port)" end if verbose - @info "Press Ctrl+D to kill the server" + @info "Press Ctrl+D to stop the server" end return server elseif parsed_args["train"]