store

Document store, United States Department of Justice, 1892 Wikimedia Commons

store transfers the selected images to image storage variables, identified by one or more command line arguments. Unless it has a + left hand decoration, store removes the selected images from the image list. With the + decorator, the duplicate remains.

Stored images may be retrieved and returned to the image list by the input command, providing as arguments image storage variables created by -store commands.

Examples

1.	Store and retrieve: Transfer an image to a variable and remove the image from the list. Restore it later in the pipeline via input.

orangecar:
   -sample car,300
   -store[-1] orangecar
   …
   -input $orangecar

Global Store: Use the underscore prefix (_) to declare globally visible storage variables. An image stored in one command can be retrieved in others. In the real world, retrievers should place such fetches in a local block and write an onfail block to catch cases where the storing command hasn't run. Observe that image labels applied through name are retrieved with the image as well.

plasmaput :
   -input 256,256,1,3
   -name. Cloud
   -plasma[Cloud] 4,5,7
   -normalize 0,{2^16-1}
   -echo "Pre-store Image list size: "$!
   -echo "Storing "{0,n}"."
   -store[Cloud] _pcloud

plasmaget :
   -echo "Post-store Image list size: "$!
   -input $_pcloud
   -echo "Retrieved: "{-1,n}
   -echo "Post-fetch Image list size: "$!

sp cat,300 store stuff i $stuff i $stuff i $stuff

3.	Duplicate:input does not delete, drain or otherwise change storage variables. Storage variables may be used to restore their related images any number of times. To get three orange cats:

threecats:
   -sample cat,300
   -store[-1] orangecat
   …
   -input $orangecat
   -input $orangecat
   -input $orangecat

   # NB. Simpler: -sample cat,300 [-1]x2 but that's no fun.

sp cat,car,monkey,300 store myimagelist $myimagelist

4.	Storing Image Lists: If a single storage variable name is given to -store, all selected images are stored in the one storage variable. Its contents are similar to an independent image list.

threethings:
   -sample cat,car,monkey,300
   -store myimagelist
   …
   -input $myimagelist

Storing Series of Single Images: Furnishing -store with more than one image storage variable induces the command to store one image per argument. In this case, the number of arguments given to store must equal the number of selected images in the right hand decorator. Since the exact number of selected images may not be apparent from the selection decorator, employing image list notation (4.) is often less error prone.

toomanyselected:
   -sample cat,car,monkey,300
   -store cat,car
[gmic]-0./ Start G'MIC interpreter.
[gmic]-1./ Input sample image 'cat' (1 image 300x275x1x3).
[gmic]-2./ Input sample image 'car' (1 image 300x200x1x3).
[gmic]-3./ Input sample image 'monkey' (1 image 300x281x1x3).
[gmic]-3./ Store images [0,1,2] as  variables 'cat,car'
[gmic]-3./ *** Error *** Command 'store': Specified arguments 'cat,car' do not match numbers of selected images.

Exchanging Data with the Math Expression Parser

store allied with the Math Expression Parser's functions store('image_storage_variable',A,_w,_h,_d,_s,_is_compressed) and get('image_storage_variable',_size,_return_as_string) furnish the means to exchange data between the two environments.

eval "foo=vector256(0);for(n=0,n<256,foo[n]=u,n=n+1);store('fooimg',foo,16,16,1,1,0)" $fooimg r2dx 256,1 n 0,255

imagefrommath:
   -eval "foo=vector256(0);
          for(n=0,n<256,foo[n]=u,n=n+1);
          store('fooimg',foo,16,16,1,1,0)"
   -input $fooimg
   -r2dx. 256,1
   -normalize. 0,255
   -output halfrandom.png

From Math variable to Image List via an Image Storage Variable: Transform a math vector into an image by providing (1) a storage variable name and (2) image dimension arguments to store() Optionally, (3) compress the image data. The given storage variable name need not already exist; it is created as necessary.


sineimg	pyeramp

gmic                                          \
    16,16,1,1,pi*x/(w-1)                      \
    vlen={wh}                                 \
    -store. pyeramp                           \
    -eval "ref(get('pyeramp',"$vlen"),rampv); \
           rampv=sin(rampv);                  \
           store('sineimg',rampv,32,8,1,1,0)" \
    -input $sineimg                           \
    -input $pyeramp                           \
    -r2dx 256,1                               \
    -normalize 0,255                          \

Round Trip With Calculations Along the Way: Image storage variables are not native math expression variables; they appear in math expressions as quoted strings, and only within store() and get() argument lists. The purpose of get() is to map an image storage variable to a native math vector. Observe that store() maps vector rampv to a new image storage variable, this with different dimensions than the original. This is permissable so long as vector lengths are observed and steps are taken that the width x height product equals the vector length of the native math variable. Note that, in practice, get() is not as commonly used as store(). Other math expression functions such as crop() may more readily map image data to native math vectors. While math expression environments disappear at the end of evaluation, image storage variables persist in concert with (but independent of) the image list. They may be referenced in subsequent math expressions, admitting the possibility of using image storage variables as a 'persistent storage' for a series of math expressions.

Command reference

$ gmic -h store

store (+):
_is_compressed={ 0 | 1 },variable_name1,_variable_name2,...

Store selected images into one or several named variables.
Selected images are transferred to the variables, and are so removed from the image list.
(except if the prepended variant of the command '+store[selection]' is used).
If a single variable name is specified, all images of the selection are assigned
to the named variable. Otherwise, there must be as many variable names as images
in the selection, and each selected image is assigned to each specified named variable.
Use command 'input $variable_name' to bring the stored images back in the list.

Default value: 'is_compressed=0'.

Example:
[#1] sample eagle,earth store img1,img2 input $img2 $img1

Tutorial: https://gmic.eu/tutorial/store

Updated: Friday February 03 2023 12:29 UTC Commit f492b9711905e4c0dacaa47e1dc2dc54e6dda677

A Full-Featured Open-Source Framework for Image Processing

Latest stable version: 3.4.3 Current pre-release: 3.5.0 (2024/12/20)

store

Examples

Exchanging Data with the Math Expression Parser

Command reference