Documentation

ION Scanner: Getting Started #

Compatible Hardware

ION Scanner will run on almost any USB web camera released in the last 10 years, but we strongly suggest purchasing an Ipevo HD Tabletop Camera, which will work without any additional configuration. For other web cams, installing manufacturer drivers may be necessary to control focus, white balance, and zoom. Video devices that require additional software to function as a webcam may work - however they are not officially supported.

Setting Up

If you are using the suggested Ipevo camera, simply unfold it and position it over the scanning area. Otherwise, you will want to mount your webcam in a stationary manner, approximately 12-24 inches above your work area. If you have multiple webcams, you will either be prompted to select one at startup, or manually specify an override device number in the preferences menu. These numbers are assigned at system boot, or as they are detected by your operating system. Laptop internal cameras (which are not officially supported) are generally given priority (#0), while external cameras are numbered sequentially after that. If you find your computer is slowing down when the camera feed is active, it may be necessary to reduce the scanning resolution and/or frame rate in the camera settings tab of the preferences.

The scanning surface should be a solid color and provide good color contrast with the border of the cards being scanned. White borders will not scan effectively on a white surface, and vice versa for black bordered cards. Direct lighting at the surface should be minimized, as it will cause strong glare which can heavily interfere with card detection.

Scanning #

When your camera is mounted and your camera feed is visible, you are ready to begin scanning cards. Card detection occurs in several discrete steps, which are as follows:

1. Waiting for a stable frame. If there is continuous motion (or light flicker) in the field of view (FoV), scanning will not begin. Make sure your hands are clear of the frame and the camera is mounted securely. If the frame is not stable, the circle indicator in the video feed will be red. If a stable frame cannot be read, increase the Noise Tolerance in the camera tab of the preferences
2. Edge detection. If an edge of the card is obscured, or contrast is poor, ION will not be able to proceed with scanning. While it is searching for edges or waiting for card input, the circle indicator will be blue.
3. Art Matching. Once a card has been detected, the detected boundaries will be drawn in the preview window briefly and the artwork of the card will be isolated and looked up in a database of all known cards. If a suitable card is not found, the indicator will flash yellow. If the card is in sleeves, and the detected edges are actually the outer perimeter of the sleeve, check the 'Dark Sleeves' box to improve classification accuracy. Increasing the Similarity Threshold in the preferences will make it more likely to return a match, but will greatly increase error rates (Default = 6)
4. Set Estimation. When a matching card is found, if that card appears with the same/similar artwork in multiple sets then ION will return all versions of the card. The list of returned cards will be sorted from best to worst match. The accuracy of this step varies greatly across lighting conditions and between hardware devices. Potential matches with mismatched border colors are moved to the bottom of the list and grayed out - Note that cards with irregular border colors may be sorted in error (7th edition foils have a black border, while their opaque counterparts do not). With 1.0.7, set detection is greatly improved, however these improvements are most noticeable only with higher end camera hardware at resolution of 1024x768 and greater.

To prevent cards from certain sets from being recommended by the set estimation step, remove them from the active sets list via the Scanning menu. Disabled sets will appear grayed out and will only be returned as the top suggestion if no active sets contain the scanned card. To prevent cards from certain sets from being detected altogether, select the "Disable Scanning" radio button from this dialog.

Hotkeys #

• SPACE: Move card from buffer to working inventory
• SPACE: Increases the quantity of the last scanned card by 1 if no card is in the buffer
• CTRL-SPACE: Adds the buffer card to list regardless of whether it is flagged as bulk or information mode is enabled
• BACKSPACE: Reduce the quantity of the last scanned card by 1 if no card is in the buffer
• ESC: Clear the buffer without adding its contents to the working inventory
• F: Mark the current buffer card as foil/non-foil
• L/R Arrow Keys: Change the edition of the card in the buffer
• U/D Arrow Keys: Change the quantity of the card in the buffer
• NUMBER KEYS 1-5: Change the condition of the card in the buffer

Inventory Management #

All cards managed by ION exist in one of 4 locations, which are as follows:

• Buffer: The current card being modified. When it is confirmed with the space bar, or another card is scanned, the buffer card is moved to the working inventory.
• Working Inventory: A list of all cards scanned in the current session, which have not yet been saved to file. These cards are both viewable and editable from the list view pane.
• Session Inventory: A list of all cards saved to the currently loaded file. These cards are viewable from the list view, but not editable
• Full Inventory: A list of all cards saved to .ion inventory files in the current directory (either that of the current file, or default location specified in the preferences)

When you save a session, the net change in all card quantities are saved to file. This means if you add a card, and later subtract it, the net change is zero and the card will not be included in the created file (Unless serial mode is activated - see below). If "Index Automatically" is enabled in the preferences, then upon start up, and whenever sessions are saved/loaded, the value of the total inventory is calculated based on the most current prices, ignoring cards with manually set prices. For very large inventories, or inventories distributed across many small files, this may take several seconds, hence why it is disabled by default. If you do not want to save a short list of scanned cards to its own file, you can add the contents of your working inventory to the end of an existing file with the Append function. The quantity of all cards will be recalculated, and cards with a net quantity of zero will be removed (Unless serial mode is activated).

By default, all saved sessions are exported with the file extension .ion; these files are plain text format, and viewable in any text or spreadsheet editor, however, changing these files may potentially render them unreadable to ION, so this is not recommended. Ideally, these files should first be exported to a comma separated values file (Export -> Session/Inventory), which will create a copy of the existing list which includes all the available data. To customize the data exported to file, see the custom export section below.

Scanning Modes #

When scanning, there are 4 modes available, which are as follows:

• Addition Mode: Scanned cards are added to the working inventory. The history view shows the most recently added/modified card at the top. If you have 3 of a card in your working inventory and scan a 4th, the top history entry will read 4. Cards can be subtracted by inputting a negative value in the quantity input box.
• Subtraction Mode: Scanned cards are subtracted from the working inventory. If you attempt to subtract a card which is not found in the full inventory, a red warning text will appear on screen. Negative values in the quantity input will ADD a card.
• Information Mode: When active, no changes will be made to the working inventory while scanning cards.
• Serial Mode: When active, cards will be appended to the working inventory, and saved to file, in the order in which they are scanned. If you scan a card which already exists in the working inventory, a new entry will be created for this card. Appending a working inventory to file with this mode active will not combine quantities, they will be added to the bottom of the list in the order they appear.

Card Details #

While a card is in the buffer, you can edit the details of the card entry by pressing the details button in the main view. From here, you can change the cards details, including name/edition, or add notes about the card, fill in the URL, or mark it as an altered, signed, or promo card (This information is stored in the Notes field). You can also edit the card details from the list view pane by pressing the '...' button. Hovering over this button will show a tooltip with any addition information that may be associated with the card. While a card is in the buffer, you can view all copies of the current card saved to files (either the current session, or any session in the current inventory folder) by navigating to the inventory tab of the list viewer.

Inventory Preview #

You can view a list of all cards saved to either the session (and working inventory), or full inventory (including session and working inventory) through the View menu.

Advanced Usage

Sounds #

By default, sounds are played when scanning cards. The sound that is played is dependent on whether a single or multiple matches are returned. If a single card is returned, a price notification can be played based on set criteria. By default, a wood block sound is played for any cards with a no available buy lists, or those value below 0.25, the $ threshold can be modified, and it can be changed to favor selling price instead. Similar criteria can be set for high value cards. Because several criteria can be true at the same time, only one sound is played based on a priority sequence. The priority is as follows: 1) Subtraction sound 2) Multiple returned cards 3) Low value 4) High value 5) Other

Enabling/Disabling Sets #

When scanning a pre-sorted collection of cards, it is possible to place a filter on the set suggestions. From the Scanning menu, the "Select Active Sets" dialog will allow you to remove one or more sets from the active suggestion list. While disabled, a set will not appear as a suggestion when scanning cards. However, if a card does not belong to any active sets, it will be scanned normally. If the "Disable Scanning" radio button is checked, then disabled cards will not scan altogether.

Preferred Merchants #

By default, all cards are exported to file using the names set by ION, which uses the printed name of the card (in ASCII format, so characters such as ?? are represented as AE). This means different printed cards may be combined into a single listing (For instance, basic lands, or cards in which multiple printed versions appear with different artwork within the same set). By setting a preferred merchant, you can use a customized naming scheme, and include product IDs for all scanned cards. This can be specified in the merchants tab of the preferences menu. The preferred merchants included are those that contribute pricing information to Trader Tools, and the product names and IDs are subject to change, to use custom specified product names and ID's, see the following section on importing custom prices.

While a preferred merchant is set, any scanned cards included in the merchants list will automatically be changed when possible. For cards with multiple listings in the preferred merchants database, a dialog will appear at the top of the screen asking the user to specify which entry corresponds to the scanned card. ION will associate the selected entry with the scanned card image, and any subsequent scanning of this card will automatically apply the selected information.

Summary Statistics #

When scanning a card, the pricing information displayed can be modified, this is also the pricing information that is exported to file. By default, the highest buylist price is shown, as is the lowest selling price. This can be changed to show the median, or mean price as well. Furthermore, the "Prefer" option specifies that ION should use the pricing information provided by the preferred merchant whenever applicable, while the "Force" option specifies that any prices from non-preferred merchants be ignored. If the user wishes to omit data from non-preferred merchants, they can individually disable merchants from the preferences menu as well.

Price Adjustments #

While a card is in the buffer, you can override the suggested price by changing the value in the two spin boxes at the bottom of the center pane. Changing the value in these boxes will only change the value of the current card in the buffer, it will not apply retroactively, or to future cards scanned. When you reload the inventory, cards with manually set prices will not have their prices updated.

The pricing information listed in the history view, inventory summaries, and exported files, are all based on the currently specified summary statistics for pricing. These can be further modified in several ways. To modify the price from a single merchant, the user can specify a gross adjustment (for instance, take 5 cents off each provided value from this merchant), a percent adjustment (increase their listed price by 10%) as well as a rounding function (always round up, down, or to the nearest 0.05 cents), applied in that order. After all individual merchant adjustments are made, a global adjustment can be applied in the same manner.

If you would like the provided pricing to be modified based on the condition of a card, this can be specified as well in the preferences. ION allows cards to be specified as Near Mint (NM), Lightly Played (LP), Moderately Played (MP), Heavily Played (HP) or Damaged (DAM).

Importing Custom Prices #

For users who wish to use their own prices, they may import a .csv file containing them. Ion does not require prices to be maintained in any specific format to import, however, the user will have to manually specify the format their prices are in before importing. The only requirement for importing is that each row is formatted identically, and the csv file includes a header - if any errors are encountered ensure the file uses UTF-8 encoding. To begin importing, open the importer through the File menu, and locate the .csv file containing the custom pricing. If the file can be read successfully, the Specify Format button should activate, click this button to proceed.

The column on the left represents a list of every header included in the imported .csv, the column on the right represents an example import tag for each column. Based on these tags, one would expect a row from the CSV to look like this:

• "Jace, Vryn's Prodigy", Magic Origins, "Condition: NM, Language: English", 15, 30, 70.0, 89.99, http://gatherer.wizards.com/Pages/Card/Details.aspx?multiverseid=398434

Text included between the %'s is interpreted as a tag, and text falling outside the tags is required to appear identically in every row. For instance, if ", Language: " is not present in every row in the input .csv, the import will fail - in these cases, some pre-processing of the imported prices may be necessary. A full list of tags can be viewed by clicking the help button.

If no %foil% tag is included, ION will assume the prices are all for non-foil prices. %foil% should be designated as "True" or "False" depending on whether the card is foil or not. If only foil cards are noted as such in the import csv, the %foilinline% tag should be used instead. This will parse the row for the word "foil" and mark any cards containing it as foil. if the %foilinline% tag is used, do not include separating spaces, hyphens etc. when specifying the format. For instance, "Jace, Vryn's Prodigy - FOIL" would be tagged as %cardname%%foilinline%

Here %volume% specifies the preferred quantity to keep in stock, whereas %quantity% specifies the number currently held. If both tags are specified, the volume displayed in the price information panes will be the difference between these two values

Once a format is specified, you may save it for future use. When specifying an input csv, if the last used format is found to be value it will automatically be loaded when opening the specification dialog.

After the list is parsed, it is saved in a format readable by ION (Resources\Databases\Local_Prices.csv), which can be manually edited in excel. If cards or sets in the input csv do not share a name with a card known to ION, the best matching card will be selected automatically. After a successful import there may be a prompt which will notify you that cards had to be renamed to match IONs naming scheme. Correct values can be remembered, and incorrect changes can be manually edited. Note that if an edition is renamed incorrectly, all cards contained within will likely be renamed incorrectly as well. If this is the case, correct the edition name and reimport before re-assigning card names. All saved changes are saved to the "Resources/Databases/Alternate Edition Names.csv" and "Alternate Card Names.csv" files in the install directory. Incorrectly applied changes can be removed by deleting rows in either of these CSVs.

If you are attempting to import prices with less specific edition names than those used by ION, you can manually map exceptions by adding lines to the "Card Import Exceptions.csv" file in the /Resources/Databases folder. When you import your price list, if an imported card shares both a name and edition with an entry in the 'importCard' and 'importEdition' column, then it will be renamed to the contents of the ionEdition and ionCard columns, respectively. If your imported list relies on the %foilinline% tag for foil parsing, then the " - foil" suffix should be included in the 'ionCard column as well.

Custom Export Formats #

If you would like the generate an output .csv OR .json file in a specific format, you may select the "Define Presets" action in the Import/Export menu to do so. You may add additional columns (or omit them by leaving them blank). Specifying field contents uses the same tagging system as the custom import. %foilinline% will use a hyphen as a separator if there is a tag or value preceding it.
In some cases, alternate naming schemes may be required for certain fields - these are the same schemes defined during a custom price import. These schemes can be enabled/disabled using the appropriate boxes. The 'Alternate Editions' option uses an alternative naming scheme that is stored in the "Resources/Databases/Alternate Edition Names.csv" file. This scheme can be edited in a plain text/spreadsheet editor. Similarly, the "Alternate Names" uses the values stored in "Resources/Databases/Alternate Card Names.csv" which, by default, includes a list of flip/transform cards incorporating both sides separated by a double slash ("//"). A preset is included for Crystal Commerce users, though, some modification may be necessary. In addition to adding new presets to the menu, you may directly export a file without saving a preset - first specify whether you would like the session (and working inventory) to be exported alone, or the full inventory contents (if the index is built), and then select OK, you will be prompted to save, and may select CSV or JSON format from the file dialog.

Batch Fills #

Note: This will overwrite any existing values!

If you would like to set the value of the notes/URL/language fields all at once you may use the batch fill dialog located in the Edit menu. For instance, if you are inputting a large number of non-English cards, rather than defining the language for each card independently, you may start a new session, scan each card normally, and then set the language for every card in the session and working inventory all at once. Select the field you wish to edit from the drop down menu (Language, Condition, Misc, or URL), and then enter the value in the text entry field below it. Changes can be previewed in the session viewer before saving.

Managing Product IDs #

While a preferred merchant is specified (including local prices) an editable drop down menu will appear in the center panel. When a scanned card contains a product ID visible to ION this center panel will display the product ID that will be saved to the inventory. Furthermore, if the scanned card has a non-standard card name (e.g. "Mountain - 244 Full Art") it will save this product name to file rather than the default ION card name ("Mountain"). If a scanned card has no specified product ID, the combo box will be highlighted in red. If a scanned card has multiple specified product IDs and it is the first time it has been seen by ION, it will also be highlighted in red. ION will default to whichever product ID was selected last upon subsequent scans of each card. Saved product ID/Card associations can be cleared by deleting "INSTALLDIR\Resources\ProductID_Listings.p".

If a card is scanned with no listed product ID, they can be manually entered by typing them into the product ID combo box. If a custom name needs to be specified as well, it can be entered after the product ID, separated by a pipe delimiter " | "

Offline Mode #

For users who anticipate unreliable internet connectivity, a computer can be marked as a trusted device from the help menu. When a device is put into offline mode, it will reduce your concurrent log in limit by 1 until disabled, however it will no longer require internet connectivity to use.
An offline device will still attempt to make outbound connections if network connectivity is available, so disabling price updates and/or wifi when on metered connections may be advisable.
Offline mode lasts for 7 days, however, it will automatically renew itself if network connectivity is present on startup. Offline mode can only be disabled from the device it is enabled on. If device hardware changes it may block attempts to disable offline mode - to regain use prior to the 7 day expiry, it may be necessary to contact support.
This feature is redundant for certain subscription plans, and thus not visible.

Customer Facing Window #

A dialog window that can be moved to a secondary display to show select information to customers or employees. Launched from the window menu, the displayed list is the current session, and the store total information is pulled from your inventory (current folder)

Specific Shortcuts:
• F11: Fullscreen (from customer window)
• ESC: Windowed (from customer window)
• CTRL-L: Save frame layout (from customer window)
• Q: Display price (from main window)

The customer window is fully customizable, each widget displayed on screen can be disabled from the separate customer settings window. Furthermore, the layout file and window theme are user editable (Layout.UI and Stylesheet.qss in the "Resources\CustomerWindow" folder). The window is built on Qt4.8 and should be editable in Qt4 Designer or QtCreator, and the stylesheet is a slightly modified CSS. For full information reference the Qt documentation. The default banner image (image0.png) can be replaced or edited, and up to 9 more images can be added (image1.png -> image9.png) if appropriate QLabel containers have been added to the layout file. By default, the price is hidden from the customer window, and can be showed by pressing the "Q" button or pressing the "Show Prices" button (visible only when this feature is enabled. This can be disabled in the settings. The remaining 2 buttons in the main window are equivalent to the add card and clear buffer functionality (Space and ESC keys). While the "Manually advance scanning" button is checked, scanning a new card will not push the current card from the buffer, instead, cards will have to be manually added with the Space bar or appropriate button before scanning will resume.

Web Integration #

If you would like to cross reference prices of scanned cards with a 3rd party site, or interface with third party hardware/software via UDP web sockets, you can do so from this tab in the preferences. Using a syntax similar to the custom import/exports, you can generate strings which will be opened in a built in web browser and/or broadcast to a specified network address either upon scanning a card or upon adding it to list.
There are a few additions between the syntax here and in the custom exporter:

• Any number of characters can be added before the end of a tag to specify whitespace replacement characters, e.g. %cardname_% and %edition % will produce "Jace_Beleren" and "Magic 2011", respectively
• Specifying a space as the whitespace replacement character will strip all whitespace - %cardname % will become "JaceBeleren"
• Percent signs that do not specify the start and end of a tag need to be preceded by an "\" escape key - %cardname\%20% will produce "Jace%20Beleren", whereas %cardname%20% would product "Jace Beleren%20" and break any tags occuring further along in the syntax string.
• Some characters which may appear in ION fields are not desired in the URL field - these can be stripped from the URL string (not the socket string). By default, colons, semicolons, periods, and commas are removed from urls, as generally these characters appear in many edition names (Duel Decks: X vs. Y) and would produce meaningless URLs.
• With 1.0.7, POST requests can be made as well. This uses the same string constructor as the web-socket broadcaster, with the notable exception that the string must be able to be parsed into a valid json.

Once syntax strings have been defined, the web socket string will be broadcast permanently, whereas the web browser syntax will be applied only when the built-in browser is opened (from the "Window" menu). If syntax is set to be applied on initial scan, it will be rebroadcast every time any of the fields contained within the syntax string change as well. If %edition% is included in your syntax, it will re-broadcast every time you flip through sets using the arrow keys. Additionally, a blank line will be broadcast over the web socket when a card is finalized and added to inventory.

MKM Integration #

MagicCardMarket.eu users can add cards directly from ION into their MKM store inventory. This functionality requires a verified seller account and can be accessed from the Import/Export menu. You will be asked to renew your login and re-authorize your account to use ION regularly. Once signed in you may:

• View your MKM store stock and download it as an ION readable file
• Add cards from the current session to your MKM inventory - if they do not currently exist in your MKM stock they will be uploaded with the current ION price assigned to them. If a matching card is found in your stock, its quantity will be incremented or decremented accordingly and the price will not be changed
• Check the price of your MKM stock against the ION pricing rules you have applied. After doing so, you can use the newly generated spin boxes to tweak any prices - the appropriate box needs to be checked for prices to be applied to your MKM inventory. When complete, pressing the Upload prices button will change these prices in your MKM stock

When using the MKM stock tool, all prices generated by ION will be converted to Euros if that is not set as the default currency from the localization menu. Additionally, since MKM uses a 7 point grading scheme, vs ION's 5, not all conditions will map 1 to 1. The following conversions will be made when uploading cards from ION:

• NM -> NM
• LP -> EX
• MP -> GD
• HP -> PL
• DAM -> PO

• M -> NM
• NM -> NM
• EX -> LP
• GD -> MP
• LP -> MP
• HP -> PL
• PO -> DAM

Other TCGs #

With ION version 1.0.7, support for additional TCGs has been added. To switch the currently active game, either select a TCG from the 'scanning' menu, or scan the back of a card. ION also supports the importing of prices from these games. To do so, ensure there is a column in the imported .csv that denotes the game. By default, MTG is assumed, otherwise, you will need a column that contains either "MTG", "YGO", or "PKM", and will need to include a %game% tag in the corresponding column. Additionally, this %game% tag will export the game when exporting a session list.