Piconso - User Guide

By: CS2103-AY1819S1-T09-3 Since: Aug 2018 Licence: MIT

1. Introduction
2. Quick Start
3. Getting started
4. Features
5. FAQ
6. Command Summary

1. Introduction

Piconso is an image-editing desktop application that is optimized for those who are familiar with Command Line Interface (CLI). If you can type fast, you may be able edit your images even faster than if you were on Photoshop! Even new users that are unfamiliar with CLI will be able to easily and quickly pick up image-editing with our simple to understand interface. Interested? Jump to the Section 2, “Quick Start” to get started. Enjoy!

2. Quick Start

Ensure you have Java version 9 or later installed in your Computer.
Download the latest piconso.jar here.
Copy the file to the folder you want to use as the home folder for your Piconso.
Double-click the file to start the app. The Graphical User Inteface (GUI) should appear in a few seconds.

3. Getting started

Let’s work through a simple project in Piconso from start to finish. In this tutorial, you will learn how to create some of the dankest memes starting from a blank template.

If you ever get stuck with a command, pop down to the Features section for reference!

Figure 1. The Piconso team knows how it feels.

Ready to start your Piconso journey?

Head over to the link here to get a zip file with all the assets you need to get started!
Unzip the files into somewhere easy to access, like your Pictures folder.
Start Piconso!
Use the cd and ls commands to get to the folder with your unzipped assets. Your current file location is as noted on the bottom right of the application. You can use the TAB key to auto-complete pesky folder names! If everything goes well, you should be able to see all the images show up in the Image Panel on the lower left.

Figure 2. Images and their corresponding indexes are showing up!

See the number below the base image? That’s the index of the image. It might be different depending on your folder’s content. If you don’t see it within the first ten images, use the next and prev command to navigate!
Open the image simply by typing open [index]. (Substitute index with the number you noted down just now)
You should see the base template in all its glory.

Figure 3. Ready to rumble.

Now we can start layering the other images on top of the base image. Let’s start by adding the coveralls logo. We do that by using the layer add command. The logo is at index 3 for us so we enter layer add 3.

Figure 4. Not exactly where we want it but it’s a start.

The logo is a bit too big for our liking so let’s resize it a bit. Start by selecting the layer that the logo is on with a quick layer select 2.
Follow up with apply resize 70% and put Coveralls down a peg or two.

Figure 5. Why don’t you pick on someone your own SIZE huh? Get it? Size?

The logo isn’t where we want it so let’s move it right to the balloon. Hit it with a layer position 295x50.

Figure 6. And that’s for rejecting my pull request!

Repeat steps 8 - 11 to place regret.png somewhere on the pink monster. Remember to select the new layer before you start to resize and reposition! (Psst. resize for 60% and move it to (5, 450) if you don’t feel like experimenting.)

Figure 7. Do androids dream of 100% code coverage?

Let’s save our work before we DEEP FRY the living daylights out of it! You can do that by typing save arrangement.png or if you’re feeling adventurous just save will overwrite your current file irreversibly.
Open our file again, refer to step 5 and 6 if you need help.
Now we can begin to use some of the more advanced features in Piconso! We add some noise to the image with apply raw +noise gaussian.
Feel free to repeat the step 15 a few times to get the desired amount of noise! We did it five times to be sure. If you ever go overboard, use the undo command to … undo the previous command. But face it, you’re going to redo it anyway.

Figure 8. Turn down for what?

Now we bump the contrast up, way way up with apply raw -contrast-stretch 15%.
Brightness and saturation gets the same boost with apply raw -modulate 120,120.
Apply the finishing touches with an unsharp mask! apply raw -unsharp 0x05. Now the meme is starting to take shape!

Figure 9. New and improved image, now with 500% more noise, 120% more brightness, 120% more saturation!

We are almost done! Repeat steps 8 - 11 again to slap some of the emojis on. You can use the apply rotate [degree] command to spice the meme up a bit. If you’re short on time, we’ve provided the exact resize and new positions:
```
For the crying emoji:
   layer position 125x330
   apply resize 20%
   apply rotate 75
```
```
For the 2 OK emojis:
   apply resize 10%
   layer position 270x390
   apply rotate 80
```

Figure 10. You’re finna gonna yeet this image.

Save the image again (save lit_meme.png) and we’re ready to upload it!
Login with the aptly named login command. Don’t worry, Piconso will never store your password in any shape or form!
Upload the file with g ul <lit_meme.png>. You should see a confirmation message when the upload is complete.
logout when you’re done! Congrats, you have just went from zero to a Piconso-certified meme hero!

Before we let you go, wonder how we made the very first image you saw? Try this before you go!

Add the base image back in, the base image will take up all the canvas space but don’t worry.
Select the layer which the original image is on and move it out of the way
```
layer select 5
layer position -450x0
```

Use canvas auto-resize on to expand the canvas to show both of them.
Remove the background color of the canvas with canvas bgcolor none or change it to something you like!

4. Features

4.1. Command Format

Items in square brackets are compulsory parameters to be added e.g convert [TRANSFORMATION]
Items in round brackets are optional parameters and can be omitted, e.g canvas size (NEW_SIZE)
For items surrounded by < >, they are compulsory parameters to be added that need to be typed with < >
- e.g g ls <ALBUM_NAME> can be used as g ls <Vacation>
Flags such as /a are compulsory flags that need to be included when using that command
- e.g g ls /a

4.2. Views help : `help`

Format: help → Shows a list of all commands.

4.3. Lists files in directory : `ls`

Format: ls → Lists all images and folders located in the current directory

4.4. Changes directory : `cd`

Format: cd [DIRECTORY_NAME] → Changes to specified directory

ℹ️	For changing of drives in Windows, add '//' after the drive name. In addition, pressing `Tab` key will autocomplete the directory name.

Example:

cd C://Users - Changes the directory to Users in C:/ drive.

4.5. Opens images for editing: `open`

Format: open [INDEX 1-10] → Opens an image for image-editing

Format: open -all → Adds all batch images in currently opened directory as layers.

Examples:

open 1
open -all [Coming in v2.0]

4.6. Retrieves the next batch of images: `next`

ℹ️	The image panel to the bottom left can only show 10 images at once, and by default will be showing the first 10 images in your directory.

Format: next → Retrieves the next 10 images for editing

4.7. Retrieves the previous batch of images: `prev`

Format: prev → Retrieves the previous 10 images for editing

4.8. Applies a transformation to an image : `apply`

There are 3 different ways to apply a transformation to an image.

Format: apply [operation] [arg1] [arg2] … → Applies the specified transformation to the selected layer (or the current image if there is only one layer).
Format: apply @Operation → Applies a custom transformation to the image, @ is compulsory.

There are many different transformations available, which we will briefly describe:

4.8.1. `blur`: Blurs your entire layer accordingly to the specified radius & sigma values.

Format: apply blur [RadiusxSigma]
- Radius (0-99): Helps in blur calculation, recommended to have a value at least twice of Sigma
- Sigma (0-99): Determines the extent of the blur
Example: apply blur 16x8

4.8.2. `motion-blur`: Simulates a motion blur on the layer

Format: apply motion-blur [RadiusxSigma+Angle]
- Radius (0-29): Helps in blur calculation, recommended to have a value at least twice of Sigma
- Sigma (0-19): Determines the extent of the blur
- Angle (0-99): Direction of the blur
Example: apply motion-blur 0x8+45

4.8.3. `colorspace`: Changes the color range of the current layer

Format: apply colorspace [color space]
- color space (sRGB/RGB/GRAY/LAB/CMYK): Changes the range of colors allowed on the image. Can be typed as upper/lower case.
Example: apply colorspace GRAY

ℹ️	For some color spaces, the image may appear to remain the same even after after changing color spaces.

4.8.4. `contrast`: Enhances the intensity differences between the lighter and darker elements

Format: apply contrast
Example: apply contrast

ℹ️	The effect of `contrast` may not very obvious depending on the image you are using. You may repeat the transformation again or use `sigmodial-contrast` instead if want further enhance the effect.

4.8.5. `sigmoidal-contrast`: Contrasts the image without saturating highlights or shadows.

Format: convert sigmoidal-contrast [ContrastxMidpoint]
- Contrast (1-99): How much to increase the contrast.
- Midpoint (1%-99%): Where the maximum change 'slope' in contrast should fall in the resultant image (0 is white; 50% is middle-gray; 100% is black).
- Example: convert sigmoidal-contrast 10x10%

4.8.6. `noise`: Increases the noise in the image

Format: apply noise [Radius]
- Radius (0-29): Determines the width of the affected area
Example: apply noise 12

4.8.7. `resize`: Resizes the image

Format: apply resize [percentage]
- Percentage (1%-300%): Percentage of resize relative to the original image.
Example: convert resize 50%

ℹ️	As all the images will be resized to the canvas when displayed, the resize command may leave an image unaffected.

4.8.8. `rotate`: Rotates an image

Format: apply rotate [value]
- Value (-360 to 360): Degree to rotate the image by. Negative values rotate the image to the anti-clockwise.
Example: convert rotate 90

4.8.9. `sharpen`: Sharpens the currently opened image

Format: apply sharpen [RadiusxSigma]
Radius (0-29): Helps in sharpen calculation.
Sigma (0-29): Determines the extent of the sharpen
Example: apply sharpen 0x8

Advanced apply command

Format: apply raw [arg1] [arg2] → Directly passes arguments entered to ImageMagick. You may refer to guide to view all operations.

Warning

Here be dragons! The raw command allows for powerful transformations but with power comes great responsibility to get your commands right. While we can tell you if an error occurs, we can’t help you more than that so be careful!

4.9. Creates custom transformation sets for use : `create`

Format: create [Name_Of_operation] [op1|arg1|arg2|…] [op2|arg1|arg2|…]: Allows you to create your own custom transformation based on the transformations specified

Example:

create blurAndRotate blur|0x8 rotate|90
- To use the newly created command, add an @ before the command used → apply @blurAndRotate

4.10. Saves images : `save`

Format: save (IMAGE_NAME): Saves the transformed image. Supports file formats jpg, jpeg, png, tiff, gif

Example:

save modified.png - Saves the image into currently opened directory as modified.png
save - Overwrites the original image in the currently opened directory. (saved as its original name)

4.11. Undoes a transformation : `undo`

Format: undo → Steps back to the previous image state (in current layer)

ℹ️	Only commands that modify the image’s transformation (anything done with `apply`) can be undone.

Example:

apply blur 0x8
apply contrast
undo → (undos the apply contrast command, image will be returned to be blur 0x8 state)

4.12. Undoes all transformations : `undo-all`

Format: undo-all → Undoes all transformations (reverts image to original state)

Example:

apply blur 0x8
apply contrast
apply rotate 90
undo-all → undoes all 3 apply commands, image will be at original state

4.13. Redoes a transformation : `redo`

Format: redo → Steps forward to the previously undone transformation

Example:

convert blur 0x8
convert contrast
undo → (undoes the apply contrast command, image will be at blur 0x8 state)
redo → (reapplies the apply contrast command)

4.14. Redoes all transformations : `redo-all`

Format: redo-all → Redoes all undone transformations

Example:

apply blur 0x8
apply contrast
apply rotate 90
undo-all (undoes all 3 convert commands, image will be at original state)
redo-all (reapplies all 3 convert commands)

4.15. Canvas operations : `canvas`

4.15.1. Changes the size of the canvas: `canvas size`

Format: canvas size (NEW_SIZE) → You can change the size of the canvas to with this command. Remember that the effects of canvas auto-resize takes precedence!
If canvas auto-resize is off, cropping might potentially occur.

ℹ️	If the optional parameter NEW_SIZE is not provided, the current size will be displayed in the output instead.

Examples:

canvas size 800x600 - Sets the canvas to have a height of 800 pixels and a width of 600px.
canvas size - Prints the current size.

4.15.2. Changes the background color of the canvas: `canvas bgcolor`

Format: canvas bgcolor (NEW_COLOR) → You can change the background color of the canvas with this command. This is only visible if the canvas is larger than all the images placed on it. See the examples for the formats that your colors can take.

ℹ️	If the optional parameter NEW_COLOUR is not provided, the current colour will be displayed in the output instead.

Examples:

canvas bgcolor none - Sets the canvas to have a transparent background.
canvas bgcolor #0f0 - Sets the canvas to the hex colour #00ff00 .
canvas bgcolor #00ff00 - Sets the canvas to the hex colour #00ff00 .
canvas bgcolor rgba(0,255,0,0.7) - Sets the canvas to the hex colour #00ff00 but with 70% opacity .
canvas bgcolor - Prints the background colour.

4.15.3. Allowing the canvas to auto-resize: `canvas auto-resize [ON|OFF]`

Format : canvas auto-resize [ON|OFF] → This command allows you to turns the auto-resize for the canvas on or off.

When auto-resize is on, it can potentially override the size manually specified with the canvas size command. When on, the canvas expands as required to ensure that no clipping occurs.

ℹ️	New canvases default to having auto-resize off.

Examples:

canvas auto-resize on - Allows the canvas to expand and prevent cropping.
canvas auto-resize off - The height and width of the output canvas will remain as is.

4.16. Layer operations : `layer`

4.16.1. Adds a new layer: `layer add [INDEX] (LAYER_NAME)`

Format : layer add [INDEX] (LAYER_NAME) → You can select the image at the provided index and add it to the current canvas with this command.

ℹ️	If the optional parameter LAYER_NAME is not provided, a name will be automatically generated.

Examples:

layer add 4 - Adds the image at index 4 to the canvas.

4.16.2. Removes a layer: `layer remove [INDEX]`

Format : layer remove [INDEX] → This command allows you to permanently removes a layer from canvas.

Warning

This operation is not reversible! Be careful when removing layers!

4.16.3. Selects a layer to work on: `layer select [INDEX]`

Format : layer select [INDEX] → This command allows you to a layer to that all apply and layer position operations will work on. The index of a layer is displayed before its name in the Layers panel.

Examples:

layer select 2 : Selects the layer at index 2.

4.16.4. Swaps the order of two layers: `layer swap [TO_INDEX] [FROM_INDEX]`

Format : layer swap [TO_INDEX] [FROM_INDEX] → You can change the order of any two distinct layers with this command. The lower the index, the further behind it will be.

Examples:

layer swap 1 2 - Changes the order of layer 1 and layer 2.

4.16.5. Positions a layer: `layer position [POSITION]`

Format : layer position [POSITION] → This command allows you to set the x and y co-ordinates of the current layer. (0,0) is defined to be the top left of the screen.

Examples:

layer position 50x100 - Sets the layer’s top left corner to be at position (50, 100).

4.17. Interact with Google Photos: `g`

Piconso allows you to connect to Google Photos so that you may easily upload and download photos for editing.

All Google-related commands will require a stable internet connection. Additionally as the following are internet-dependant, the commands will take a longer amount of time to execute as compared to the other offline features.

Connecting to Google Photos is NOT compulsory, it is simply an additional feature to supplement your experience with Piconso!

ℹ️	The higher the amount of images involved in your google command, the longer amount of time commands will take to process.

4.17.1. Logs in to Google Photos: `login`

Format : login → Allows you to connect to Google Photos through a browser redirect

4.17.2. Traverses Google Photos: `g ls`

Format: g ls (parameters) → Lists the images you have in Google Photos.

There are 3 ways you can list your images.

g ls: Lists all images in your account
g ls /a: Lists all your available albums
g ls <ALBUM_NAME>: Lists all images in specified album from Google Photos.

Examples:

* g ls <Vacation> - Lists all images in the Vacation album.

4.17.3. Downloads photos from Google Photos: `g dl`

Format: g dl [parameters] → Downloads your specified image from Google Photos.

ℹ️	All photos will be downloaded to the currently opened local directory. Any files with duplicate naming existing in the targeted directory WILL be replaced

There are 3 ways you can list your images:

g dl /i<IMAGE_NAME> : Downloads the specified image from Google Photos
g dl /a<ALBUM_NAME> : Downloads all images from the specified album into Google Photos.
g dl /a<ALBUM_NAME> /i<IMAGE_NAME> : Downloads a specific photo from a specific album in Google Photos.

Examples:

g dl /i<Beach.png> - Downloads Beach.png
g dl /a<Vacation> - Downloads all photos from Vacation album
g dl /a<Vacation> /i<Beach.png> - Downloads Beach.png from Vacation album

4.17.4. Uploads photos to Google Photos: `g ul`

Format: g ul [parameters] → Uploads your specified image to Google Photos.

ℹ️	All uploaded photos will be automatically categorised into album 'Piconso Uploads' in Google Photos. Any duplicate images in Google Photos will be replaced by the new upload with the old name.

There are 2 ways you can list your images:

g ul <IMAGE_NAME> : Uploads the specified image to Google Photos
g ul all : Uploads all images in current opened directory to Google Photos.

Examples:

g ul <Cat.png> - Uploads Cat.png

4.18. Logs out of Google Photos: `logout`

Format: logout → Disconnects you from Google Photos

4.19. Exits the application: `exit`

Format: exit → Closes the application

5. FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous folder.

6. Command Summary

Help : help
Ls : ls
Cd : cd [DIRECTORY_NAME]
Open : open [INDEX 1-10]
e.g. open 1
Next : next
Previous : prev
Apply apply [TRANSFORMATION]
e.g. apply rotate 180
Save : save [IMAGE_NAME]/[SET_NAME]
e.g. save exampleImage.jpg
Undo : undo
Undo All : undo-all
Redo : redo
Redo All : redo-all
Canvas auto-resize : canvas auto-resize [on/off]
Background color : canvas bgcolor [color]
Canvas size : canvas size (heightxwidth)
Add layer : layer add [INDEX]
Delete layer : layer delete [INDEX]
Reposition layer : layer position [newXxnewY]
Select layer : layer select [INDEX]
Swap the order of two layers : layer swap [INDEX 1] [INDEX 2]
Login : login
Google List : g ls OR g ls /a OR g ls <ALBUM_NAME>
Download : g dl /i<IMAGE_NAME> OR g dl /a<ALBUM_NAME> OR g dl /a<ALBUM_NAME> /i<IMAGE_NAME>
Upload : g ul <IMAGE_NAME> OR g ul all
Logout : logout
Exit : exit

Files

UserGuide.adoc

Latest commit

History

UserGuide.adoc

File metadata and controls

Piconso - User Guide

1. Introduction

2. Quick Start

3. Getting started

4. Features

4.1. Command Format

4.2. Views help : help

4.3. Lists files in directory : ls

4.4. Changes directory : cd

4.5. Opens images for editing: open

4.6. Retrieves the next batch of images: next

4.7. Retrieves the previous batch of images: prev

4.8. Applies a transformation to an image : apply

4.8.1. blur: Blurs your entire layer accordingly to the specified radius & sigma values.

4.8.2. motion-blur: Simulates a motion blur on the layer

4.8.3. colorspace: Changes the color range of the current layer

4.8.4. contrast: Enhances the intensity differences between the lighter and darker elements

4.8.5. sigmoidal-contrast: Contrasts the image without saturating highlights or shadows.

4.8.6. noise: Increases the noise in the image

4.8.7. resize: Resizes the image

4.8.8. rotate: Rotates an image

4.8.9. sharpen: Sharpens the currently opened image

4.9. Creates custom transformation sets for use : create

4.10. Saves images : save

4.11. Undoes a transformation : undo

4.12. Undoes all transformations : undo-all

4.13. Redoes a transformation : redo

4.14. Redoes all transformations : redo-all

4.15. Canvas operations : canvas

4.15.1. Changes the size of the canvas: canvas size

4.15.2. Changes the background color of the canvas: canvas bgcolor

4.15.3. Allowing the canvas to auto-resize: canvas auto-resize [ON|OFF]

4.16. Layer operations : layer

4.16.1. Adds a new layer: layer add [INDEX] (LAYER_NAME)

4.16.2. Removes a layer: layer remove [INDEX]

4.16.3. Selects a layer to work on: layer select [INDEX]

4.16.4. Swaps the order of two layers: layer swap [TO_INDEX] [FROM_INDEX]

4.16.5. Positions a layer: layer position [POSITION]

4.17. Interact with Google Photos: g

4.17.1. Logs in to Google Photos: login

4.17.2. Traverses Google Photos: g ls

4.17.3. Downloads photos from Google Photos: g dl

4.17.4. Uploads photos to Google Photos: g ul

4.18. Logs out of Google Photos: logout

4.19. Exits the application: exit

5. FAQ

6. Command Summary

4.2. Views help : `help`

4.3. Lists files in directory : `ls`

4.4. Changes directory : `cd`

4.5. Opens images for editing: `open`

4.6. Retrieves the next batch of images: `next`

4.7. Retrieves the previous batch of images: `prev`

4.8. Applies a transformation to an image : `apply`

4.8.1. `blur`: Blurs your entire layer accordingly to the specified radius & sigma values.

4.8.2. `motion-blur`: Simulates a motion blur on the layer

4.8.3. `colorspace`: Changes the color range of the current layer

4.8.4. `contrast`: Enhances the intensity differences between the lighter and darker elements

4.8.5. `sigmoidal-contrast`: Contrasts the image without saturating highlights or shadows.

4.8.6. `noise`: Increases the noise in the image

4.8.7. `resize`: Resizes the image

4.8.8. `rotate`: Rotates an image

4.8.9. `sharpen`: Sharpens the currently opened image

4.9. Creates custom transformation sets for use : `create`

4.10. Saves images : `save`

4.11. Undoes a transformation : `undo`

4.12. Undoes all transformations : `undo-all`

4.13. Redoes a transformation : `redo`

4.14. Redoes all transformations : `redo-all`

4.15. Canvas operations : `canvas`

4.15.1. Changes the size of the canvas: `canvas size`

4.15.2. Changes the background color of the canvas: `canvas bgcolor`

4.15.3. Allowing the canvas to auto-resize: `canvas auto-resize [ON|OFF]`

4.16. Layer operations : `layer`

4.16.1. Adds a new layer: `layer add [INDEX] (LAYER_NAME)`

4.16.2. Removes a layer: `layer remove [INDEX]`

4.16.3. Selects a layer to work on: `layer select [INDEX]`

4.16.4. Swaps the order of two layers: `layer swap [TO_INDEX] [FROM_INDEX]`

4.16.5. Positions a layer: `layer position [POSITION]`

4.17. Interact with Google Photos: `g`

4.17.1. Logs in to Google Photos: `login`

4.17.2. Traverses Google Photos: `g ls`

4.17.3. Downloads photos from Google Photos: `g dl`

4.17.4. Uploads photos to Google Photos: `g ul`

4.18. Logs out of Google Photos: `logout`

4.19. Exits the application: `exit`