Tools

bq-dirupload : upload local files to remote system

bq-dirfetch : download remote files to local system

Configuration

Create a file config file containing you login info at ~/.config/viqi/profiles or ~/config/viqi/profiles on Windows

    [default]
    host=https://science.viqiai.cloud/
    user=demo
    password=<demopass>

    [client1]
    host=https://science.viqiai.cloud/
    user=client1@someplace.org
    password=<demopass>

    [user2]
    host=https://science.viqiai.cloud/
    user=user2@someplace.com
    password=<demopass>

    [user2-testing]
    host=https://testing.viqiai.dev/
    user=user2@someplace.com
    password=<demopass>

bq-dirupload

1. Upload directories and files to a ViQi/BisQue server

usage: Upload files to bisque [-h] [-c CONFIG] [--profile PROFILE] [-n] [-d [DEBUG]] [--debug-file DEBUG_FILE] [-q] [-a CREDENTIALS] [--host HOST] [--user USER] [--password PASSWORD] [--alias ALIAS] [--tag TAG]
                              [--path-tags PATH_TAGS] [--re-tags RE_TAGS] [--re-only] [--mustmap] [--include INCLUDE] [--exclude EXCLUDE] [--dataset DATASET] [--threads THREADS] [--empty] [-s] [-r]
                              [--tagmap TAGMAP] [--fixedtags FIXEDTAGS] [--json-args JSON_ARGS] [--protocol {binary,fsxlustre,multipart}] [--destination-dir DESTINATION_DIR] [--transfer-only]
                              [--register-only REGISTER_ONLY] [--archive-type {zip-bisque,zip-multi-file,zip-time-series,zip-z-stack,zip-dicom}] [--watch]
                              [directories ...]

positional arguments:
  directories           director(ies) to upload

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        bisque config
  --profile PROFILE     Profile to use in bisque config
  -n, --dry-run         report actions w/o changes
  -d [DEBUG], --debug [DEBUG]
                        set debug level: debug,info,warn,error
  --debug-file DEBUG_FILE
                        output filename for debug messages
  -q, --quiet           print actions
  -a CREDENTIALS, --credentials CREDENTIALS
                        A bisque login.. admin
  --host HOST           Default bisque server to connect to
  --user USER           User to connect with
  --password PASSWORD   passwor to connect with
  --alias ALIAS         Use admin credentials to login as alias
  --tag TAG             Add name:value pair, can be templated with other values mycode:$site$season
  --path-tags PATH_TAGS
                        tag names for a parsable path i.e. /root/project/date//subject/ or \root\project\data\subject
  --re-tags RE_TAGS     re expressions for tags i.e. (?P<location>\w+)--(?P<date>[\d-]+)
  --re-only             Accept files only if match re-tags
  --mustmap             Contextual tag must have a value in a tagmap
  --include INCLUDE     shell expression for files to include. Can be repeated
  --exclude EXCLUDE     shell expression for files to exclude. Can be repeated
  --dataset DATASET     create dataset and add files to it
  --threads THREADS     set number of uploader threads
  --empty               Allow empty files to be uploaded
  -s, --skip-loaded     Skip upload if there is file with the same name already present on the server
  -r, --replace-uploaded
                        Force upload of metadata even if file exists on server
  --tagmap TAGMAP       Supply a map tag/value -> tag/value found in tag path and re decoder. [context_key:]carp=carpenteria or [context_key:]@tagmap.csv
  --fixedtags FIXEDTAGS
                        key:tag=value or key:@fileoftags fixed tags to add to resource: First column is key: including filename or image_path
  --json-args JSON_ARGS
                        Load default arguments from json file i.e { "--path-tags" : "project/date" }
  --protocol {binary,fsxlustre,multipart}
                        Set the upload protocol or let tyhe system choose
  --destination-dir DESTINATION_DIR
                        Upload to destination-dir on server .. must be valid mount i.e /home/my-uploads
  --transfer-only       Upload files only without registration
  --register-only REGISTER_ONLY
                        register files without actually uploading them use argument as prefix path for
  --archive-type {zip-bisque,zip-multi-file,zip-time-series,zip-z-stack,zip-dicom}
                        zip archive will be given a type: bisque, z-stack, t-stack
  --watch               Watch directories listed for new files and transfer

bq-dirupload -n  --threads 1 --re-tags "(?P<photo_site_code>\w+)_(?P<target_assemblage>\D+)(?P<plot>\d+)_(?P<season>\D+)(?P<year>\d+).+\.JPG" --dataset upload --tagmap target_assemblage:@speciesmap.csv --tagmap photo_site_code:@locationmap.csv --tagmap season:fa=fall --tagmap year:15=2015 --fixedtags photo_site_code:@photo_code_reference_2019_0912.csv TopLevelDir

 Magic decoder ring:
    -n : dry run
    --threads 1: one thread for debugging
    --retags :   use filename to create tags: photo_site_code, target_assemblage, season and year.
    --dataset : create a dataset "upload"
    --tagmap target_assemblage:@speciesmap.csv: use value ins speciesmap.csv to rename tag/values for target_assemblage
    --tagmap photo_site_code:@locationmap: Use location map to rename tag/value from photo_site_code
    --tagmap season:fa=fall : rename season 'fa' to 'fall'
    --tagmap year:15=2015 : remame year from '15' to 2015
    --fixedtags photo_site_code:@photo_code_reference_2019_0912.csv  :  use photo_site_code to read a set of fixed tags to be applied to the resource

   A map is consists of [context_tag:]oldval=newval or [context_tag:]@map.csv where csv is a two column table of old value, new value

Other interesting Arguments

    --debug-file somefile :  write actions to somefile
    --path-tags   map components of the file path  to metadata tags i.e.   on the path ghostcrabs/manua/winter/somefile.jpg
                  --path-tags=project/site/season  ->  { project:ghostcrabs, site:manua, season:winter} as tags on somefile.jpg
                  --path-tags=/site//              ->  {site:manua }   skipping root and season elements

Examples

1. Simple decoding of path/filename into metadata tags

   bq-dirupload --skip --include *.JPG --tag activity:bear --re-tags "(?P<location>\w+)_(?P<camera>\w+)__(?P<date>[\d-]+)__(?P<time>[\d-]+).*" ~/Desktop/pics/bears/

2. Complex mapping of path/filename metadata into tag

   bq-dirupload -n --threads 1 --re-tags "(?P<photo_site_code>\w+)_(?P<target_assemblage>\D+)(?P<plot>\d+)_(?P<season>\D+)(?P<year>\d+).+\.JPG" --dataset upload --tagmap target_assemblage:@speciesmap.csv --tagmap photo_site_code:@locationmap.csv --tagmap season:fa=fall --tagmap year:15=2015 --fixedtags photo_site_code:@photo_code_reference_2019_0912.csv

Magic decoder ring:

    -n : dry run to see action without doing them
    --threads 1: one thread for debugging
    --retags :   use filename to create tags: photo_site_code, target_assemblage, season and year.
    --dataset : create a dataset "upload"
    --tagmap target_assemblage:@speciesmap.csv: use value ins speciesmap.csv to rename tag/values for target_assemblage
    --tagmap photo_site_code:@locationmap: Use location map to rename tag/value from photo_site_code
    --tagmap season:fa=fall : rename season 'fa' to 'fall'
    --tagmap year:15=2015 : remame year from '15' to 2015
    --fixedtags photo_site_code:@photo_code_reference_2019_0912.csv  :  use photo_site_code to read a set of fixed tags to be applied to the resource

   A map is consists of [context_tag:]oldval=newval or [context_tag:]@map.csv where csv is a two column table of old value, new value

Other interesting Arguments

    --debug-file somefile :  write actions to somefile
    --path-tags   map components of the file path  to metadata tags i.e. project/site/season   would map ghostcrabs/manua/winter/somefile.jpg
                  would get { project:ghostcrabs, site:manua, season:winter} as tags on somefile.jpg

bq-dirfetch

Downoad files to the local fileystsem

usage: Fetch files from bisque [-h] [-c CONFIG] [--profile PROFILE] [-n]
                               [-d [DEBUG]] [--debug-file DEBUG_FILE] [-q]
                               [-a CREDENTIALS] [--bisque-host BISQUE_HOST]
                               [--alias ALIAS] [--threads THREADS]
                               [--meta {false,xml,tablecsv,json}]
                               [--view VIEW]
                               [datasets [datasets ...]]

positional arguments:
  datasets              datasets to download

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        bisque config
  --profile PROFILE     Profile to use in bisque config
  -n, --dry-run         report actions w/o changes
  -d [DEBUG], --debug [DEBUG]
                        set debug level: debug,info,warn,error
  --debug-file DEBUG_FILE
                        output filename for debug messages
  -q, --quiet           print actions
  -a CREDENTIALS, --credentials CREDENTIALS
                        A bisque login.. admin
  --bisque-host BISQUE_HOST
                        Default bisque server to connect to
  --alias ALIAS         Use admin credentials to login as alias
  --threads THREADS     set number of uploader threads
  --meta {false,xml,tablecsv,json}
                        fetch metadata of resources: xml, tablecsv or false
  --view VIEW           Metadata view i.e. deep,clean or view=TAG1,TAG2

bq-dirfetch -n  --threads 1 dataset_uri

Examples

  $ bq-dirfetch  https://data.viqi.org/data_service/00-aGLFAaVudK2SesxZbFgtSA
  $ ls My\ data

  30PKCVampNFp1Exte_DSP.tif   30PKCVampNFp6Exte_DSP.tif 30PKCVampNFz5Live5-21-2004_2-21-06_PM.tif  'My Data.tablecsv'
  30PKCVampNFp3Exte_DSP.tif   30PKCVampNFz1Live5-21-2004_1-36-13_PM.tif   D4P1.TIF
  $ cat My\ data/My\ Data.tablecsv
  name,filename,tag1,tag1.subtag1,upload_datetime
  D4P1.TIF,D4P1.TIF,,,2021-04-06 11:45:25.939292
  30PKCVampNFp1Exte_DSP.tif,30PKCVampNFp1Exte_DSP.tif,,,2021-04-06 11:47:12.354264
  30PKCVampNFp3Exte_DSP.tif,30PKCVampNFp3Exte_DSP.tif,,,2021-04-06 11:53:07.626649
  30PKCVampNFp6Exte_DSP.tif,30PKCVampNFp6Exte_DSP.tif,val1,subval1,2021-04-06 11:54:38.046633
  30PKCVampNFz1Live5-21-2004_1-36-13_PM.tif,30PKCVampNFz1Live5-21-2004_1-36-13_PM.tif,,,2021-04-06 12:07:28.216727
  30PKCVampNFz5Live5-21-2004_2-21-06_PM.tif,30PKCVampNFz5Live5-21-2004_2-21-06_PM.tif,,,2021-04-06 12:12:12.523292

Advanced Configuration and Arguments

Pass a file of arguments with --json-args=path-to-file.json where path-to-file.json has:

{
    "directories"   : [ "tmp", "tmp1" ],
    "--path-tags"   : "top/d1/d2",
    "--profile"     : "hq"
}

Furthermore you can use an environment variable to pass this information

export BQ_OEM_TRANSFER=path-to-file.json