From f5ae383d388348dace59ab0965a3c475009f7c1f Mon Sep 17 00:00:00 2001 From: VietThanLinux Date: Thu, 11 Aug 2022 21:38:27 -0400 Subject: [PATCH 1/2] Slight changes to README for explicit information My girlfriend didn't know [what is on the terminal vs python](https://stackoverflow.com/questions/59795354/what-does-the-dollar-sign-represent-in-front-of-lines) --- README.md | 42 +++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index ca1879ff..646fbfa9 100644 --- a/README.md +++ b/README.md @@ -8,51 +8,51 @@ See the [change log](https://github.com/YaleDHLab/pix-plot/wiki/Change-Log) for ## Dependencies -To install the Python dependencies, we recommend you [install Anaconda](https://www.anaconda.com/products/individual#Downloads) and then create a conda environment with a Python 3.7 runtime: +To install the Python dependencies, we recommend you [install Anaconda](https://www.anaconda.com/products/individual#Downloads) and then create a conda environment with a Python 3.7 runtime. The following is example on the terminal: ```bash -conda create --name=3.7 python=3.7 -source activate 3.7 +$ conda create --name=3.7 python=3.7 +$ source activate 3.7 ``` Then you can install the dependencies by running: ```bash -pip uninstall pixplot -pip install https://github.com/yaledhlab/pix-plot/archive/master.zip +$ pip uninstall pixplot +$ pip install https://github.com/yaledhlab/pix-plot/archive/master.zip ``` -Please note that you will need to use Python 3.6 or Python 3.7 to install and use this package. The HTML viewer also requires a WebGL-enabled browser. +Please note that you will need to use Python 3.6 or Python 3.7 to install and use this package. The HTML viewer also _**requires a WebGL-enabled browser**_. ## Quickstart If you have a WebGL-enabled browser and a directory full of images to process, you can prepare the data for the viewer by installing the dependencies above then running: ```bash -pixplot --images "path/to/images/*.jpg" +$ pixplot --images "path/to/images/*.jpg" ``` To see the results of this process, you can start a web server by running: ```bash # for python 3.x -python -m http.server 5000 +$ python -m http.server 5000 # for python 2.x -python -m SimpleHTTPServer 5000 +$ python -m SimpleHTTPServer 5000 ``` -The visualization will then be available at `http://localhost:5000/output`. +The visualization will then be available at http://localhost:5000/output. ## Sample Data -To acquire some sample data with which to build a plot, feel free to use some data prepared by Yale's DHLab: +To acquire some sample data with which to build a plot, feel free to use some data prepared by Yale's DHLab. Run the following on your terminal: ```bash -pip install image_datasets +$ pip install image_datasets ``` -Then in a Python script: +Then in Python, run: ```python import image_datasets @@ -62,7 +62,7 @@ image_datasets.oslomini.download() The `.download()` command will make a directory named `datasets` in your current working directory. That `datasets` directory will contain a subdirectory named 'oslomini', which contains a directory of images and another directory with a CSV file of image metadata. Using that data, we can next build a plot: ```bash -pixplot --images "datasets/oslomini/images/*" --metadata "datasets/oslomini/metadata/metadata.csv" +$ pixplot --images "datasets/oslomini/images/*" --metadata "datasets/oslomini/metadata/metadata.csv" ``` ## Creating Massive Plots @@ -70,7 +70,7 @@ pixplot --images "datasets/oslomini/images/*" --metadata "datasets/oslomini/meta If you need to plot more than 100,000 images but don't have an expensive graphics card with which to visualize huge WebGL displays, you might want to specify a smaller "cell_size" parameter when building your plot. The "cell_size" argument controls how large each image is in the atlas files; smaller values require fewer textures to be rendered, which decreases the GPU RAM required to view a plot: ```bash -pixplot --images "path/to/images/*.jpg" --cell_size 10 +$ pixplot --images "path/to/images/*.jpg" --cell_size 10 ``` ## Controlling UMAP Layout @@ -86,7 +86,7 @@ The [UMAP algorithm](https://github.com/lmcinnes/umap) is particularly sensitive UMAP's creator, Leland McInnes, has written up a [helpful overview of these hyperparameters](https://umap-learn.readthedocs.io/en/latest/parameters.html). To specify the value for one or more of these hyperparameters when building a plot, one may use the flags above, e.g.: ```bash -pixplot --images "path/to/images/*.jpg" --n_neighbors 2 +$ pixplot --images "path/to/images/*.jpg" --n_neighbors 2 ``` ## Curating Automatic Hotspots @@ -100,7 +100,7 @@ If you have metadata associated with each of your images, you can pass in that m To specify the metadata for your image collection, you can add ` --metadata=path/to/metadata.csv` to the command you use to call the processing script. For example, you might specify: ```bash -pixplot --images "path/to/images/*.jpg" --metadata "path/to/metadata.csv" +$ pixplot --images "path/to/images/*.jpg" --metadata "path/to/metadata.csv" ``` Metadata should be in a comma-separated value file, should contain one row for each input image, and should contain headers specifying the column order. Here is a sample metadata file: @@ -126,9 +126,10 @@ The following column labels are accepted: ## IIIF Images -If you would like to process images that are hosted on a IIIF server, you can specify a newline-delimited list of IIIF image manifests as the `--images` argument. For example, the following could be saved as `manifest.txt`: +If you would like to process images that are hosted on a IIIF server, you can specify a newline-delimited list of IIIF image manifests as the `--images` argument. For example, the following create a `manifest.txt` that contains links to the images, for example: ```bash +$ cat manifest.txt # print out contents of manifest.txt https://manifests.britishart.yale.edu/manifest/40005 https://manifests.britishart.yale.edu/manifest/40006 https://manifests.britishart.yale.edu/manifest/40007 @@ -136,7 +137,10 @@ https://manifests.britishart.yale.edu/manifest/40008 https://manifests.britishart.yale.edu/manifest/40009 ``` -One could then specify these images as input by running `pixplot --images manifest.txt --n_clusters 2` +One could then specify these images as input by running on the terminal: +```bash +$ pixplot --images manifest.txt --n_clusters 2 +``` ## Demonstrations (Developed with PixPlot 2.0 codebase) From e33bb2790fa7a3e59b47dbcc53e4ec3fb808e86c Mon Sep 17 00:00:00 2001 From: VietThanLinux Date: Thu, 11 Aug 2022 21:47:54 -0400 Subject: [PATCH 2/2] slight wording change --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 646fbfa9..9ec6e1a0 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ $ pip uninstall pixplot $ pip install https://github.com/yaledhlab/pix-plot/archive/master.zip ``` -Please note that you will need to use Python 3.6 or Python 3.7 to install and use this package. The HTML viewer also _**requires a WebGL-enabled browser**_. +Please note that you will need to use Python 3.6 or Python 3.7 to install and use this package. The HTML viewer also _**requires a WebGL-enabled browser**_ (most modern browsers updated to the latest version has this enabled to default but no guarantees). ## Quickstart